gdc-sdk-client-ts 1.0.4 → 1.1.0

package/README.md

@@ -141,14 +141,14 @@ The `SmartTokenManager` within the SDK handles this flow automatically. API serv
 
 1.  **The `API_INTEGRATORS_GUIDE.md` is the Source of Truth:** All API method implementations, service selectors, and payload structures **must** be based on the official documentation available at `https://raw.githubusercontent.com/Global-DataCare/docs/refs/heads/main/API_INTEGRATORS_GUIDE.md`. The SDK should not invent or assume logic.
 2.  **Test Data is the Second Source of Truth:** The mock data files in `client-sdk-ts/__tests__/data/` are sourced from the backend's own test suite and documentation. They represent the ground truth for API responses and **must** be used for all Jest tests and for the in-app `DEMO_MODE`.
-3.  **Specific Methods are Simple, The Engine is Smart:** A specific API method (e.g., `createOrganization`) is responsible for knowing the "what" (the endpoint selector, the payload). The `BaseApiService` engine (`resolveAndExecute`) is responsible for the "how" (DID resolution, message construction, job submission).
+3.  **Specific Methods are Simple, The Engine is Smart:** A specific API method (e.g., `startOrganizationRegistration`) is responsible for knowing the "what" (the endpoint selector, the payload). The `BaseApiService` engine (`resolveAndExecute`) is responsible for the "how" (DID resolution, message construction, job submission).
 
 ## End-to-End Onboarding Flow
 
 The SDK is designed to follow a specific, multi-step business process for onboarding a new organization.
 
-1.  **`orgAdmin.admin.createOrganization()`**: A legal representative, authenticated with an external OIDC `id_token`, submits the organization's details to the **Host Provider's DID**. The async response will contain an `Offer`.
-2.  **`orgAdmin.admin.confirmOrder()`**: The representative accepts the offer by submitting an order, again to the **Host Provider's DID**. The async response will contain a set of license codes.
+1.  **`orgAdmin.admin.startOrganizationRegistration()`**: A legal representative, authenticated with an external OIDC `id_token`, submits the organization's details. The SDK automatically resolves and targets the operator host DID for this onboarding call. The async response will contain an `Offer`.
+2.  **`orgAdmin.admin.confirmOrganizationRegistration()`**: The representative accepts the offer by submitting an order. The SDK again resolves the operator host DID automatically. The async response will contain a set of license codes.
 3.  **Payment (External)**: If required, the user completes the payment flow.
 4.  **`common.auth.activateDevice()`**: The representative (or another employee) uses a valid license code to register their device. This is a DCR (Dynamic Client Registration) call made to the **Gateway's (Tenant's) DID**. This call creates the `client_id` (`did:web`) for the device and marks it as active.
 5.  **`smartToken` Acquisition**: From this point forward, all API calls are authorized (Post-DCR) and must acquire a `smartToken`. The SDK handles this automatically using the device's identity (via `private_key_jwt`) and the user's `id_token`.
@@ -316,16 +316,15 @@ const session = await sdk.initializeSession({
 const orgAdminService = session.orgAdmin.admin;
 
 // --- Step 2: Create the Organization ---
-// This call is directed at the HOST's DID.
-const hostDid = 'did:web:provider.example.com';
+// The SDK derives the operator host DID from `providerDid`.
 const orgClaims = { /* ... organization registration data ... */ };
-const { thid: createOrgThid } = await orgAdminService.createOrganization(orgClaims, hostDid, legalRepIdToken);
+const { thid: createOrgThid } = await orgAdminService.startOrganizationRegistration(orgClaims, legalRepIdToken);
 // Poll for the result, which will contain an Offer...
 
 // --- Step 3: Confirm the Order ---
-// The user accepts the offer. This call is also to the HOST's DID.
+// The user accepts the offer. The SDK keeps targeting the operator host DID internally.
 const offerId = '...'; // From the result of the previous step
-const { thid: confirmOrderThid } = await orgAdminService.confirmOrder(offerId, hostDid, legalRepIdToken);
+const { thid: confirmOrderThid } = await orgAdminService.confirmOrganizationRegistration(offerId, legalRepIdToken);
 // Poll for the result, which will contain a license code...
 
 // --- Step 4: Activate the First Device ---
@@ -337,7 +336,7 @@ const { thid: activateThid } = await commonAuthService.activateDevice(licenseCod
 ```
 
 ### Note on Production vs. Test Onboarding
-The self-service `createOrganization` flow detailed above is intended for the **`test-network`**. Onboarding a new organization in the **production** environment involves a manual verification process by the host provider to ensure the legitimacy of the legal entity.
+The self-service `startOrganizationRegistration` flow detailed above is intended for the **`test-network`**. Onboarding a new organization in the **production** environment involves a manual verification process by the host provider to ensure the legitimacy of the legal entity.
 
 ## Testing
 

package/dist/ClientSDK.d.ts

@@ -15,6 +15,7 @@ export interface InitializeSessionParams {
     role: string;
     providerDid: string;
     appType?: AppInfo['appType'];
+    familyId?: string;
 }
 /**
  * @class ClientSDK
@@ -49,6 +50,7 @@ export declare class ClientSDK {
      */
     initializeProfileRegistry(createVault: (registryId: string) => IVaultRepository, registryId?: string): Promise<ProfileRegistry>;
     shutdownSession(): void;
+    private normalizeRoleCodeForDid;
     private constructEmployeeDid;
     private constructIndividualDid;
 }

package/dist/ClientSDK.js

@@ -130,7 +130,7 @@ export class ClientSDK {
         const finalProfileId = params.profileId || this.sdkConfig.crypto.randomUUID();
         const userDid = appType === 'Organization'
             ? this.constructEmployeeDid(providerDid, email, role)
-            : this.constructIndividualDid(providerDid, finalProfileId);
+            : await this.constructIndividualDid(providerDid, finalProfileId, email, role, params.familyId);
         const publicKeys = await this.wallet.provisionKeys(finalProfileId);
         const newProfile = {
             id: finalProfileId,
@@ -174,25 +174,29 @@ export class ClientSDK {
             this.currentSession = null;
         }
     }
-    constructEmployeeDid(connectorDid, email, role) {
-        // The user's role is expected in the FHIR-like format "system|code", e.g., "ISCO-08|1120"
-        const roleParts = role.split('|');
-        if (roleParts.length !== 2) {
-            console.warn(`[ClientSDK] Invalid role format for Employee DID construction: ${role}. Expected "system|code".`);
-            return `${connectorDid}:employee:invalid-role-format`;
+    normalizeRoleCodeForDid(role, fallback = 'unknown-role') {
+        const raw = (role || '').trim();
+        if (!raw)
+            return fallback;
+        const parts = raw.split('|');
+        if (parts.length === 2) {
+            return (parts[1] || '').trim() || fallback;
         }
-        // Construct the DID according to the official spec in docs/did_generation.md
-        const rawDid = `${connectorDid}:employee:${email}:${role}`;
+        return raw;
+    }
+    constructEmployeeDid(connectorDid, email, role) {
+        const roleCode = this.normalizeRoleCodeForDid(role, 'invalid-role');
+        const rawDid = `${connectorDid}:employee:${email}:${roleCode}`;
         // Normalize it to ensure canonical representation
         return normalizeDidWeb(rawDid);
     }
-    // TODO: Per conversation, evolve this to align with the new path structure,
-    // potentially incorporating a familyId. e.g., did:web:<provider>:family:<id>:individual:<uuid_base58>
-    constructIndividualDid(connectorDid, profileId) {
-        // For now, using a simplified version of the multibase approach.
-        // A real implementation would use a proper base58btc encoder.
-        const multibaseId = `z${profileId.replace(/-/g, '')}`;
-        const rawDid = `${connectorDid}:individual:multibase:${multibaseId}`;
+    async constructIndividualDid(connectorDid, profileId, email, role, familyId) {
+        const normalizedEmail = (email || '').trim().toLowerCase();
+        const emailHash = await this.sdkConfig.crypto.digestString(normalizedEmail, 'SHA-256');
+        const multibaseEmailHash = `z${emailHash}`;
+        const normalizedFamilyId = (familyId || `profile-${profileId}`).trim();
+        const normalizedRole = this.normalizeRoleCodeForDid(role, 'ONESELF').toUpperCase();
+        const rawDid = `${connectorDid}:family:${normalizedFamilyId}:${multibaseEmailHash}:${normalizedRole}`;
         return normalizeDidWeb(rawDid);
     }
 }

package/dist/frontend-services/BaseApiService.d.ts

@@ -34,6 +34,7 @@ export declare abstract class BaseApiService {
     protected readonly appInfo: AppInfo;
     protected readonly cryptoHelper: ICryptoHelper;
     constructor(context: ServiceContext);
+    private withRetryPolicy;
     /**
      * The generic "engine" for all API calls. It takes the endpoint ingredients,
      * builds the selector, finds the service, constructs the message, and executes the job.

package/dist/frontend-services/BaseApiService.js

@@ -25,6 +25,26 @@ export class BaseApiService {
         this.appInfo = context.appInfo; // Initialize AppInfo
         this.cryptoHelper = context.cryptoHelper;
     }
+    async withRetryPolicy(operationKey, fn) {
+        var _a, _b, _c, _d;
+        const policy = (_b = (_a = this.sdkConfig.api).getRetryPolicy) === null || _b === void 0 ? void 0 : _b.call(_a, operationKey);
+        const retries = Math.max(0, (_c = policy === null || policy === void 0 ? void 0 : policy.retries) !== null && _c !== void 0 ? _c : 0);
+        const delayMs = Math.max(0, (_d = policy === null || policy === void 0 ? void 0 : policy.delayMs) !== null && _d !== void 0 ? _d : 0);
+        const attempts = retries + 1;
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < attempts && delayMs > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error(`Operation failed: ${operationKey}`);
+    }
     /**
      * The generic "engine" for all API calls. It takes the endpoint ingredients,
      * builds the selector, finds the service, constructs the message, and executes the job.
@@ -69,16 +89,17 @@ export class BaseApiService {
             jti: this.jobManager.generateId(),
             thid: thid,
         };
+        const operationKey = `${serviceSelector.section || 'default'}/${serviceSelector.format}/${serviceSelector.resourceType}/${serviceSelector.action}`;
         // 6. Call the appropriate execution method.
         if (isPublic) {
             if (!idToken)
                 throw new Error("idToken is required for public jobs.");
-            await this.executePublicJob(endpointUrl, idToken, didcommMessage, serviceSelector);
+            await this.withRetryPolicy(operationKey, () => this.executePublicJob(endpointUrl, idToken, didcommMessage, serviceSelector));
         }
         else {
             if (!requiredScope || !idToken)
                 throw new Error("requiredScope and idToken are required for authorized jobs.");
-            await this.executeAuthorizedJob(targetDid, endpointUrl, requiredScope, idToken, didcommMessage, serviceSelector);
+            await this.withRetryPolicy(operationKey, () => this.executeAuthorizedJob(targetDid, endpointUrl, requiredScope, idToken, didcommMessage, serviceSelector));
         }
         return { thid };
     }

package/dist/frontend-services/org-admin/OrgAdminService.d.ts

@@ -3,15 +3,20 @@ import { BaseApiService } from "../BaseApiService";
 * Service class for handling organization-related administrative actions.
 */
 export declare class OrgAdminService extends BaseApiService {
+    /**
+    * Resolves the operator host DID from the current session provider DID.
+    * For hosted organizations (`did:web:host:tenant:...`) this returns `did:web:host`.
+    * For self-hosted organizations (`did:web:org.example.com`) this returns the same DID.
+    */
+    private resolveOperatorDidFromSession;
     /**
     * Registers a new organization with the gateway using an external OIDC token.
     *
     * @param dataClaims The organization's registration form data.
-    * @param gatewayDid The DID of the target gateway/host.
     * @param idToken The OIDC token of the legal representative.
     * @returns The thread ID (thid) of the submitted job for polling.
     */
-    createOrganization(dataClaims: object, gatewayDid: string, idToken: string, targetNetwork: string): Promise<{
+    startOrganizationRegistration(dataClaims: object, idToken: string, targetNetwork?: string): Promise<{
         thid: string;
     }>;
     /**
@@ -19,11 +24,10 @@ export declare class OrgAdminService extends BaseApiService {
     * This is the second step in the organization onboarding flow.
     *
     * @param acceptedOfferId The URN identifier of the offer being accepted.
-    * @param gatewayDid The DID of the target gateway/host.
     * @param idToken The OIDC token of the legal representative.
     * @returns The thread ID (thid) of the submitted job for polling.
     */
-    confirmOrder(acceptedOfferId: string, gatewayDid: string, idToken: string, targetNetwork: string): Promise<{
+    confirmOrganizationRegistration(acceptedOfferId: string, idToken: string, targetNetwork?: string): Promise<{
         thid: string;
     }>;
     /**

package/dist/frontend-services/org-admin/OrgAdminService.js

@@ -1,21 +1,37 @@
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
 // File: client-sdk-ts/src/services/org-admin/OrgAdminService.ts
 import { BaseApiService } from "../BaseApiService.js";
-import { EndpointKey, ENDPOINT_REGISTRY } from "../../serviceSelectorRegistry.js";
+import { EndpointKey, ENDPOINT_REGISTRY, defaultNetworkIdentifier } from "../../serviceSelectorRegistry.js";
 /**
 * Service class for handling organization-related administrative actions.
 */
 export class OrgAdminService extends BaseApiService {
+    /**
+    * Resolves the operator host DID from the current session provider DID.
+    * For hosted organizations (`did:web:host:tenant:...`) this returns `did:web:host`.
+    * For self-hosted organizations (`did:web:org.example.com`) this returns the same DID.
+    */
+    resolveOperatorDidFromSession() {
+        const providerDid = this.profile.providerDid;
+        if (!providerDid || !providerDid.startsWith('did:web:')) {
+            throw new Error(`[OrgAdminService] Invalid provider DID in session: '${providerDid}'.`);
+        }
+        const parts = providerDid.split(':');
+        if (parts.length < 3) {
+            throw new Error(`[OrgAdminService] Invalid provider DID format: '${providerDid}'.`);
+        }
+        return `did:web:${parts[2]}`;
+    }
     /**
     * Registers a new organization with the gateway using an external OIDC token.
     *
     * @param dataClaims The organization's registration form data.
-    * @param gatewayDid The DID of the target gateway/host.
     * @param idToken The OIDC token of the legal representative.
     * @returns The thread ID (thid) of the submitted job for polling.
     */
-    async createOrganization(dataClaims, gatewayDid, idToken, targetNetwork) {
-        console.log(`[OrgAdminService] Calling createOrganization on network: ${targetNetwork}.`);
+    async startOrganizationRegistration(dataClaims, idToken, targetNetwork = defaultNetworkIdentifier) {
+        console.log(`[OrgAdminService] Calling startOrganizationRegistration on network: ${targetNetwork}.`);
+        const operatorDid = this.resolveOperatorDidFromSession();
         const serviceSelector = Object.assign({}, ENDPOINT_REGISTRY[EndpointKey.REGISTER_TENANT]);
         serviceSelector.sector = targetNetwork;
         const payloadBody = {
@@ -24,7 +40,7 @@ export class OrgAdminService extends BaseApiService {
                     meta: { claims: dataClaims },
                 }],
         };
-        return this.resolveAndExecute(gatewayDid, serviceSelector, payloadBody, true, // isPublic
+        return this.resolveAndExecute(operatorDid, serviceSelector, payloadBody, true, // isPublic
         undefined, idToken);
     }
     /**
@@ -32,12 +48,12 @@ export class OrgAdminService extends BaseApiService {
     * This is the second step in the organization onboarding flow.
     *
     * @param acceptedOfferId The URN identifier of the offer being accepted.
-    * @param gatewayDid The DID of the target gateway/host.
     * @param idToken The OIDC token of the legal representative.
     * @returns The thread ID (thid) of the submitted job for polling.
     */
-    async confirmOrder(acceptedOfferId, gatewayDid, idToken, targetNetwork) {
-        console.log(`[OrgAdminService] Calling confirmOrder for offer: ${acceptedOfferId} on network: ${targetNetwork}.`);
+    async confirmOrganizationRegistration(acceptedOfferId, idToken, targetNetwork = defaultNetworkIdentifier) {
+        console.log(`[OrgAdminService] Calling confirmOrganizationRegistration for offer: ${acceptedOfferId} on network: ${targetNetwork}.`);
+        const operatorDid = this.resolveOperatorDidFromSession();
         const serviceSelector = Object.assign({}, ENDPOINT_REGISTRY[EndpointKey.CONFIRM_ORDER]);
         serviceSelector.sector = targetNetwork;
         const payloadBody = {
@@ -51,7 +67,7 @@ export class OrgAdminService extends BaseApiService {
                     }
                 }],
         };
-        return this.resolveAndExecute(gatewayDid, serviceSelector, payloadBody, true, // isPublic
+        return this.resolveAndExecute(operatorDid, serviceSelector, payloadBody, true, // isPublic
         undefined, idToken);
     }
     /**

package/dist/interfaces/others.d.ts

@@ -39,6 +39,10 @@ export interface INetwork {
 export interface IApiConfig {
     operationMode: 'DEMO' | 'FAPI';
     legacyFhirEnabled: boolean;
+    getRetryPolicy?: (operationKey: string) => {
+        retries: number;
+        delayMs: number;
+    } | undefined;
 }
 /**
  * Defines the set of optional parameters for enabling the SDK's mock mode.

package/dist/utils/entitlements.d.ts

@@ -0,0 +1,10 @@
+export type LicenseClass = 'member' | 'employee';
+export type OfferEntitlement = {
+    offerId?: string;
+    checkoutUrl?: string;
+    quantity?: number;
+    unitPrice?: string;
+    totalPrice?: string;
+    taxes?: string;
+};
+export declare const parseOfferEntitlementFromClaims: (claims: Record<string, any> | undefined) => OfferEntitlement;

package/dist/utils/entitlements.js

@@ -0,0 +1,21 @@
+const findClaimBySuffix = (claims, suffix) => {
+    if (!claims)
+        return undefined;
+    for (const [key, value] of Object.entries(claims)) {
+        if (typeof value === 'string' && key.endsWith(suffix))
+            return value;
+    }
+    return undefined;
+};
+export const parseOfferEntitlementFromClaims = (claims) => {
+    const quantityRaw = findClaimBySuffix(claims, 'Offer.eligibleQuantity.value');
+    const quantity = typeof quantityRaw === 'string' && quantityRaw.trim().length > 0 ? Number(quantityRaw) : undefined;
+    return {
+        offerId: findClaimBySuffix(claims, 'Offer.identifier'),
+        checkoutUrl: findClaimBySuffix(claims, 'Offer.checkoutPageURLTemplate'),
+        quantity: Number.isFinite(quantity) ? quantity : undefined,
+        unitPrice: findClaimBySuffix(claims, 'Offer.unitPrice.value'),
+        totalPrice: findClaimBySuffix(claims, 'Offer.price.value'),
+        taxes: findClaimBySuffix(claims, 'Offer.tax.value'),
+    };
+};

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from './mockData';
 export * from './scopeBuilder';
 export * from './rule';
+export * from './entitlements';

package/dist/utils/index.js

@@ -4,3 +4,4 @@
 export * from './mockData.js';
 export * from './scopeBuilder.js';
 export * from './rule.js';
+export * from './entitlements.js';

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "gdc-sdk-client-ts",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "private": false,
   "type": "module",
   "dependencies": {
     "@noble/hashes": "^1.8.0",
-    "gdc-common-utils-ts": "^1.0.7"
+    "gdc-common-utils-ts": "^1.1.0"
   },
   "scripts": {
     "test": "jest",