gdc-common-utils-ts 2.0.15 → 2.0.17

package/dist/utils/gw-core-commercial-contract.d.ts

@@ -0,0 +1,41 @@
+import { ClaimsOfferSchemaorg, ClaimsOrderSchemaorg } from '../constants/schemaorg';
+/**
+ * Canonical GW CORE onboarding/reissue flow identifiers for commercial
+ * expectations.
+ *
+ * These identifiers are intentionally flow-level, not transport-level:
+ * - they describe whether one GW response is expected to mint a commercial
+ *   Offer and whether a follow-up `Order/_batch` step is part of the contract
+ * - they do not describe how the caller reached the flow (PDF, ICA proof,
+ *   signed bundle, SDK facade, etc.)
+ */
+export declare const GwCoreCommercialFlow: Readonly<{
+    readonly LegalOrganizationTransaction: "legal-organization-transaction";
+    readonly LegalOrganizationActivateLegacy: "legal-organization-activate-legacy";
+    readonly LegalOrganizationIssueReissue: "legal-organization-issue-reissue";
+    readonly IndividualOrganizationCommercial: "individual-organization-commercial";
+    readonly IndividualOrganizationEmbeddedRegistration: "individual-organization-embedded-registration";
+}>;
+export type GwCoreCommercialFlow = typeof GwCoreCommercialFlow[keyof typeof GwCoreCommercialFlow];
+export type GwCoreCommercialContract = Readonly<{
+    flow: GwCoreCommercialFlow;
+    mintsOffer: boolean;
+    requiresOrderConfirmation: boolean;
+    offerClaim?: typeof ClaimsOfferSchemaorg.identifier;
+    orderClaim?: typeof ClaimsOrderSchemaorg.acceptedOfferIdentifier;
+    programmingHint: string;
+}>;
+/**
+ * Shared commercial contract table for the GW CORE onboarding/reissue flows
+ * that currently matter to SDKs, BFFs and route-level tests.
+ *
+ * Reading guide:
+ * - `mintsOffer=true` means the response is expected to expose the canonical
+ *   commercial claim in `meta.claims['org.schema.Offer.identifier']`
+ * - `requiresOrderConfirmation=true` means the caller must later submit
+ *   `Order.acceptedOffer.identifier` through `Order/_batch`
+ * - `mintsOffer=false` means the flow is not expected to create a new
+ *   commercial Offer, even if it returns activation material or other claims
+ */
+export declare const GW_CORE_COMMERCIAL_CONTRACTS: Readonly<Record<GwCoreCommercialFlow, GwCoreCommercialContract>>;
+export declare function readGwCoreCommercialContract(flow: GwCoreCommercialFlow): GwCoreCommercialContract;

package/dist/utils/gw-core-commercial-contract.js

@@ -0,0 +1,71 @@
+import { ClaimsOfferSchemaorg, ClaimsOrderSchemaorg } from '../constants/schemaorg.js';
+/**
+ * Canonical GW CORE onboarding/reissue flow identifiers for commercial
+ * expectations.
+ *
+ * These identifiers are intentionally flow-level, not transport-level:
+ * - they describe whether one GW response is expected to mint a commercial
+ *   Offer and whether a follow-up `Order/_batch` step is part of the contract
+ * - they do not describe how the caller reached the flow (PDF, ICA proof,
+ *   signed bundle, SDK facade, etc.)
+ */
+export const GwCoreCommercialFlow = Object.freeze({
+    LegalOrganizationTransaction: 'legal-organization-transaction',
+    LegalOrganizationActivateLegacy: 'legal-organization-activate-legacy',
+    LegalOrganizationIssueReissue: 'legal-organization-issue-reissue',
+    IndividualOrganizationCommercial: 'individual-organization-commercial',
+    IndividualOrganizationEmbeddedRegistration: 'individual-organization-embedded-registration',
+});
+/**
+ * Shared commercial contract table for the GW CORE onboarding/reissue flows
+ * that currently matter to SDKs, BFFs and route-level tests.
+ *
+ * Reading guide:
+ * - `mintsOffer=true` means the response is expected to expose the canonical
+ *   commercial claim in `meta.claims['org.schema.Offer.identifier']`
+ * - `requiresOrderConfirmation=true` means the caller must later submit
+ *   `Order.acceptedOffer.identifier` through `Order/_batch`
+ * - `mintsOffer=false` means the flow is not expected to create a new
+ *   commercial Offer, even if it returns activation material or other claims
+ */
+export const GW_CORE_COMMERCIAL_CONTRACTS = Object.freeze({
+    [GwCoreCommercialFlow.LegalOrganizationTransaction]: {
+        flow: GwCoreCommercialFlow.LegalOrganizationTransaction,
+        mintsOffer: true,
+        requiresOrderConfirmation: true,
+        offerClaim: ClaimsOfferSchemaorg.identifier,
+        orderClaim: ClaimsOrderSchemaorg.acceptedOfferIdentifier,
+        programmingHint: 'Use this for first-time legal organization onboarding; read meta.claims[org.schema.Offer.identifier] and then confirm Order/_batch.',
+    },
+    [GwCoreCommercialFlow.LegalOrganizationActivateLegacy]: {
+        flow: GwCoreCommercialFlow.LegalOrganizationActivateLegacy,
+        mintsOffer: true,
+        requiresOrderConfirmation: true,
+        offerClaim: ClaimsOfferSchemaorg.identifier,
+        orderClaim: ClaimsOrderSchemaorg.acceptedOfferIdentifier,
+        programmingHint: 'Legacy ICA-proof activation still mints one commercial Offer and still requires Order/_batch confirmation.',
+    },
+    [GwCoreCommercialFlow.LegalOrganizationIssueReissue]: {
+        flow: GwCoreCommercialFlow.LegalOrganizationIssueReissue,
+        mintsOffer: false,
+        requiresOrderConfirmation: false,
+        programmingHint: 'Use this only to reissue controller activation material for an already existing tenant; do not expect a new Offer or Order step.',
+    },
+    [GwCoreCommercialFlow.IndividualOrganizationCommercial]: {
+        flow: GwCoreCommercialFlow.IndividualOrganizationCommercial,
+        mintsOffer: true,
+        requiresOrderConfirmation: true,
+        offerClaim: ClaimsOfferSchemaorg.identifier,
+        orderClaim: ClaimsOrderSchemaorg.acceptedOfferIdentifier,
+        programmingHint: 'Use this for the family/individual commercial bootstrap facade that returns one Offer and then requires Order/_batch.',
+    },
+    [GwCoreCommercialFlow.IndividualOrganizationEmbeddedRegistration]: {
+        flow: GwCoreCommercialFlow.IndividualOrganizationEmbeddedRegistration,
+        mintsOffer: false,
+        requiresOrderConfirmation: false,
+        programmingHint: 'Use this only for embedded legacy subject registration inside an already active tenant; it signals status but does not mint a commercial Offer.',
+    },
+});
+export function readGwCoreCommercialContract(flow) {
+    return GW_CORE_COMMERCIAL_CONTRACTS[flow];
+}

package/dist/utils/index.d.ts

@@ -31,6 +31,8 @@ export * from './fhir-cid';
 export * from './fhir-search';
 export * from './family-organization-summary';
 export * from './gw-core-path';
+export * from './gw-core-commercial-contract';
+export * from './legal-organization-verification-result';
 export * from './communication-fhir-r4';
 export * from './communication-document-reference';
 export * from './communication-bundle-document-request';

package/dist/utils/index.js

@@ -31,6 +31,8 @@ export * from './fhir-cid.js';
 export * from './fhir-search.js';
 export * from './family-organization-summary.js';
 export * from './gw-core-path.js';
+export * from './gw-core-commercial-contract.js';
+export * from './legal-organization-verification-result.js';
 export * from './communication-fhir-r4.js';
 export * from './communication-document-reference.js';
 export * from './communication-bundle-document-request.js';

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

@@ -0,0 +1,37 @@
+export type LegalOrganizationVerificationCredential = Record<string, unknown>;
+export type LegalOrganizationVerificationCredentialPair = Readonly<{
+    verificationEntries: readonly unknown[];
+    organizationCredential: LegalOrganizationVerificationCredential;
+    legalRepresentativeCredential: LegalOrganizationVerificationCredential;
+}>;
+/**
+ * Returns the ICA verification entries currently projected by GW host
+ * legal-organization `_transaction`.
+ *
+ * Supported shapes:
+ * - direct `vc[]` projection on the first response entry
+ * - nested `resource.icaResponse.body.data[]`
+ * - direct ICA `_verify-response` bodies reused in tests/docs
+ */
+export declare function getLegalOrganizationVerificationEntriesFromResponseBody(responseBody: unknown): unknown[];
+/**
+ * Reads the organization and legal-representative credentials returned by the
+ * legal-organization verification flow.
+ */
+export declare function readLegalOrganizationVerificationCredentialPairFromResponseBody(responseBody: unknown): LegalOrganizationVerificationCredentialPair;
+/**
+ * Reads the canonical organization tax id from the verification credential
+ * pair and enforces agreement between organization and representative VC when
+ * both values are present.
+ */
+export declare function readLegalOrganizationVerificationTaxIdFromResponseBody(responseBody: unknown): string;
+/**
+ * Reads `credentialSubject.sameAs` from the legal-representative credential
+ * when present.
+ */
+export declare function readLegalRepresentativeSameAsFromResponseBody(responseBody: unknown): string | undefined;
+/**
+ * Reads `credentialSubject.hasCredential.material` continuity data from the
+ * legal-representative credential when present.
+ */
+export declare function readLegalRepresentativeBindingFromResponseBody(responseBody: unknown): string | undefined;

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

@@ -0,0 +1,106 @@
+import { extractCredentialSubject, extractOrganizationTaxId, extractRepresentativeCredentialBinding, extractRepresentativeMemberOfTaxId, } from './activation-policy.js';
+function asObject(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    return value;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function findCredentialResource(entries, expectedTypeFragment, fallbackIndex) {
+    const byType = entries.find((entry) => {
+        const candidate = asObject(entry);
+        const typeValue = candidate?.type;
+        const tokens = Array.isArray(typeValue)
+            ? typeValue.map((token) => String(token || ''))
+            : [String(typeValue || '')];
+        return tokens.some((token) => token.includes(expectedTypeFragment));
+    });
+    const selected = asObject(byType) || asObject(entries[fallbackIndex]);
+    const resource = asObject(selected?.resource) || selected;
+    if (!resource) {
+        throw new Error(`Missing '${expectedTypeFragment}' verification credential in legal-organization verification response.`);
+    }
+    return resource;
+}
+/**
+ * Returns the ICA verification entries currently projected by GW host
+ * legal-organization `_transaction`.
+ *
+ * Supported shapes:
+ * - direct `vc[]` projection on the first response entry
+ * - nested `resource.icaResponse.body.data[]`
+ * - direct ICA `_verify-response` bodies reused in tests/docs
+ */
+export function getLegalOrganizationVerificationEntriesFromResponseBody(responseBody) {
+    const root = asObject(responseBody) || {};
+    const topLevelEntries = asArray(root.data);
+    const bodyEntries = asArray(asObject(root.body)?.data);
+    const firstEntry = asObject(bodyEntries[0]) || asObject(topLevelEntries[0]) || {};
+    const projectedCredentials = asArray(firstEntry.vc);
+    if (projectedCredentials.length >= 2) {
+        return projectedCredentials;
+    }
+    const nestedIcaResponse = asObject(asObject(firstEntry.resource)?.icaResponse) || {};
+    const nestedBodyEntries = asArray(asObject(nestedIcaResponse.body)?.data);
+    if (nestedBodyEntries.length >= 2) {
+        return nestedBodyEntries;
+    }
+    const nestedTopLevelEntries = asArray(nestedIcaResponse.data);
+    if (nestedTopLevelEntries.length >= 2) {
+        return nestedTopLevelEntries;
+    }
+    if (bodyEntries.length >= 2) {
+        return bodyEntries;
+    }
+    if (topLevelEntries.length >= 2) {
+        return topLevelEntries;
+    }
+    throw new Error('Legal-organization verification response is missing ICA verification credential entries.');
+}
+/**
+ * Reads the organization and legal-representative credentials returned by the
+ * legal-organization verification flow.
+ */
+export function readLegalOrganizationVerificationCredentialPairFromResponseBody(responseBody) {
+    const verificationEntries = getLegalOrganizationVerificationEntriesFromResponseBody(responseBody);
+    return {
+        verificationEntries,
+        organizationCredential: findCredentialResource(verificationEntries, 'Organization', 0),
+        legalRepresentativeCredential: findCredentialResource(verificationEntries, 'LegalRepresentative', 1),
+    };
+}
+/**
+ * Reads the canonical organization tax id from the verification credential
+ * pair and enforces agreement between organization and representative VC when
+ * both values are present.
+ */
+export function readLegalOrganizationVerificationTaxIdFromResponseBody(responseBody) {
+    const pair = readLegalOrganizationVerificationCredentialPairFromResponseBody(responseBody);
+    const organizationTaxId = extractOrganizationTaxId(pair.organizationCredential);
+    const representativeTaxId = extractRepresentativeMemberOfTaxId(pair.legalRepresentativeCredential);
+    const resolvedTaxId = organizationTaxId || representativeTaxId;
+    if (!resolvedTaxId) {
+        throw new Error('Legal-organization verification response is missing organization tax id in both organization and representative credentials.');
+    }
+    if (organizationTaxId && representativeTaxId && organizationTaxId !== representativeTaxId) {
+        throw new Error('Legal-organization verification response contains mismatched organization tax ids between organization and representative credentials.');
+    }
+    return resolvedTaxId;
+}
+/**
+ * Reads `credentialSubject.sameAs` from the legal-representative credential
+ * when present.
+ */
+export function readLegalRepresentativeSameAsFromResponseBody(responseBody) {
+    const pair = readLegalOrganizationVerificationCredentialPairFromResponseBody(responseBody);
+    return String(extractCredentialSubject(pair.legalRepresentativeCredential)?.sameAs || '').trim() || undefined;
+}
+/**
+ * Reads `credentialSubject.hasCredential.material` continuity data from the
+ * legal-representative credential when present.
+ */
+export function readLegalRepresentativeBindingFromResponseBody(responseBody) {
+    const pair = readLegalOrganizationVerificationCredentialPairFromResponseBody(responseBody);
+    return extractRepresentativeCredentialBinding(pair.legalRepresentativeCredential);
+}

package/package.json

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