gdc-sdk-node-ts 0.12.0 → 2.0.4

package/dist/backend-profile-runtime.js

@@ -0,0 +1,498 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { ActorKinds } from 'gdc-common-utils-ts/constants/actor-session';
+import { ProfileAppTypes } from 'gdc-common-utils-ts/constants';
+import { JobStatus } from 'gdc-common-utils-ts/models/confidential-job';
+import { buildActorSessionDescriptorForActorKind, expandActorSessionDescriptorToFacades, prepareLoadedActorProfile, prepareLoadProfile, } from 'gdc-sdk-core-ts';
+import { createActorSessionsFromFacades } from './gdc-session-bridge.js';
+export const BackendSubjectIndexReadModes = Object.freeze({
+    LatestIps: 'latest-ips',
+    ClinicalBundle: 'clinical-bundle',
+});
+/**
+ * Default backend-generic runtime implementation backed by injected adapters.
+ *
+ * This class is the first concrete v2 slice intended for backend consumers that
+ * need one reusable actor-aware profile runtime after authentication.
+ */
+export class BackendProfileRuntime {
+    constructor(adapters, options = {}) {
+        this.adapters = adapters;
+        this.options = options;
+    }
+    async loadProfile(input) {
+        const loadedProfile = await this.adapters.loadProfile(input);
+        return {
+            ...loadedProfile,
+            actorSessions: createActorSessionsFromFacades(loadedProfile.facades, this.options.facadeClient),
+        };
+    }
+    async closeProfile(_profileKey) { }
+    async registerTrustedDevice(input) {
+        return this.adapters.registerTrustedDevice(input);
+    }
+    async connectToSubjectIndex(input) {
+        return this.adapters.connectToSubjectIndex(input);
+    }
+    async getSubjectIndexComposition(input) {
+        return this.adapters.getSubjectIndexComposition(input);
+    }
+}
+/**
+ * Current concrete backend profile runtime over one injected runtime client.
+ *
+ * This is the pragmatic v2 bridge for backend consumers that already possess
+ * an authenticated `RuntimeClient` and need `loadProfile(...)` to materialize
+ * actor facades immediately against the current GW CORE contract.
+ */
+export class DirectBackendProfileRuntime {
+    constructor(options) {
+        this.loadedProfiles = new Map();
+        this.options = options;
+    }
+    async loadProfile(input) {
+        const normalized = prepareLoadProfile(input);
+        const profileId = String(normalized.profileId
+            || normalized.profileDid
+            || normalized.subjectDid
+            || normalized.providerDid).trim();
+        const resolvedAppType = normalized.appType || ProfileAppTypes.Family;
+        const descriptor = {
+            profileId,
+            actorKind: normalized.actorKind,
+            actorRole: normalized.actorRole,
+            providerDid: normalized.providerDid,
+            runtimeClass: normalized.runtimeClass,
+            profileDid: normalized.profileDid,
+            subjectDid: normalized.subjectDid,
+            email: normalized.email,
+            phone: normalized.phone,
+            deviceDid: normalized.deviceDid,
+            appType: resolvedAppType,
+        };
+        const session = buildActorSessionDescriptorForActorKind({
+            actorKind: normalized.actorKind,
+            appType: resolvedAppType,
+            profileId: descriptor.profileId,
+            profileDid: descriptor.profileDid,
+            role: descriptor.actorRole,
+        });
+        const facades = expandActorSessionDescriptorToFacades(session);
+        const jobManager = this.options.createJobManager
+            ? this.options.createJobManager(descriptor, normalized)
+            : createJobManagerInMemory(descriptor);
+        const loadedProfile = prepareLoadedActorProfile({
+            descriptor,
+            session,
+            facades,
+            jobManager,
+        });
+        const backendProfile = {
+            ...loadedProfile,
+            actorSessions: createActorSessionsFromFacades(loadedProfile.facades, this.options.facadeClient),
+        };
+        this.rememberLoadedProfile(backendProfile);
+        return backendProfile;
+    }
+    async closeProfile(profileKey) {
+        const profile = this.resolveLoadedProfile(profileKey);
+        profile.jobManager.shutdown();
+        this.forgetLoadedProfile(profile);
+    }
+    async registerTrustedDevice(input) {
+        if (this.options.registerTrustedDevice) {
+            return this.options.registerTrustedDevice(input);
+        }
+        return {
+            trustedDeviceId: input.deviceDid,
+            status: 'already-trusted',
+        };
+    }
+    async connectToSubjectIndex(input) {
+        if (this.options.connectToSubjectIndex) {
+            return this.options.connectToSubjectIndex(input);
+        }
+        return {
+            subjectId: input.subjectId,
+            userId: input.userId,
+            userRoleCode: input.userRoleCode,
+            status: 'already-connected',
+        };
+    }
+    async getSubjectIndexComposition(input) {
+        if (this.options.getSubjectIndexComposition) {
+            return this.options.getSubjectIndexComposition(input);
+        }
+        const routeContext = this.options.defaultRouteContext;
+        if (!routeContext) {
+            throw new Error('DirectBackendProfileRuntime requires defaultRouteContext to read subject index data.');
+        }
+        const profile = this.resolveLoadedProfile(input.userId);
+        if (profile.descriptor.actorKind !== ActorKinds.IndividualController) {
+            throw new Error(`DirectBackendProfileRuntime currently resolves subject index reads through IndividualController only, not '${profile.descriptor.actorKind}'.`);
+        }
+        const sdk = requireBackendIndividualControllerSdk(profile);
+        if (this.options.subjectIndexReadMode === BackendSubjectIndexReadModes.ClinicalBundle) {
+            const searchResult = await sdk.searchClinicalBundle(routeContext, {
+                subject: input.subjectId,
+            });
+            return {
+                subjectId: input.subjectId,
+                userId: input.userId,
+                userRoleCode: input.userRoleCode,
+                composition: searchResult.poll.body,
+            };
+        }
+        const latestIps = await sdk.getLatestIps(routeContext, {
+            subject: input.subjectId,
+        });
+        return {
+            subjectId: input.subjectId,
+            userId: input.userId,
+            userRoleCode: input.userRoleCode,
+            composition: latestIps.poll.body,
+        };
+    }
+    rememberLoadedProfile(profile) {
+        const keys = new Set([
+            profile.descriptor.profileId,
+            String(profile.descriptor.profileDid || '').trim(),
+            String(profile.descriptor.subjectDid || '').trim(),
+            String(profile.descriptor.email || '').trim(),
+            String(profile.descriptor.phone || '').trim(),
+        ].filter(Boolean));
+        for (const key of keys) {
+            this.loadedProfiles.set(key, profile);
+        }
+    }
+    forgetLoadedProfile(profile) {
+        const keys = new Set([
+            profile.descriptor.profileId,
+            String(profile.descriptor.profileDid || '').trim(),
+            String(profile.descriptor.subjectDid || '').trim(),
+            String(profile.descriptor.email || '').trim(),
+            String(profile.descriptor.phone || '').trim(),
+        ].filter(Boolean));
+        for (const key of keys) {
+            this.loadedProfiles.delete(key);
+        }
+    }
+    resolveLoadedProfile(userId) {
+        const normalizedUserId = String(userId || '').trim();
+        const direct = this.loadedProfiles.get(normalizedUserId);
+        if (direct) {
+            return direct;
+        }
+        throw new Error(`DirectBackendProfileRuntime has not loaded one backend profile for '${normalizedUserId}'.`);
+    }
+}
+/**
+ * Preferred developer-facing factory for the current backend profile runtime.
+ *
+ * Use this helper in tutorials and app/BFF code when you already have one
+ * configured runtime client and want the canonical
+ * `loadProfile(...) -> session -> actor facade` entrypoint without exposing the
+ * concrete class name in every example.
+ */
+export function createBackendProfileRuntime(options) {
+    return new DirectBackendProfileRuntime(options);
+}
+/**
+ * Minimal in-memory `JobManager` for backend runtimes that do not need durable
+ * persistence during one live session.
+ */
+export function createJobManagerInMemory(descriptor) {
+    let isInitialized = false;
+    let sequence = 0;
+    const jobs = new Map();
+    let listener;
+    function notify() {
+        listener?.();
+    }
+    function nextSequence() {
+        sequence += 1;
+        return sequence;
+    }
+    function inferFormType(content) {
+        const first = Array.isArray(content?.body?.data) ? content.body.data[0] : undefined;
+        return String(first?.type || content?.type || '').trim();
+    }
+    function cloneJob(job) {
+        return {
+            ...job,
+            indexed: job.indexed ? structuredClone(job.indexed) : job.indexed,
+            content: job.content ? structuredClone(job.content) : job.content,
+            jwe: job.jwe ? structuredClone(job.jwe) : job.jwe,
+        };
+    }
+    function matchesQuery(job, query) {
+        const conditions = Array.isArray(query.where) ? query.where : [];
+        return conditions.every((condition) => {
+            const currentValue = job[condition.attribute];
+            if ('equals' in condition) {
+                return currentValue === condition.equals;
+            }
+            if ('in' in condition) {
+                return Array.isArray(condition.in) && condition.in.includes(currentValue);
+            }
+            return true;
+        });
+    }
+    return {
+        descriptor: { ...descriptor },
+        get isInitialized() {
+            return isInitialized;
+        },
+        async initialize() {
+            isInitialized = true;
+        },
+        shutdown() {
+            isInitialized = false;
+            jobs.clear();
+        },
+        setListener(nextListener) {
+            listener = nextListener;
+        },
+        async createJob(content, selector) {
+            const now = Date.now();
+            const job = {
+                id: createRuntimeUuid(),
+                thid: String(content?.thid || '').trim() || undefined,
+                status: JobStatus.DRAFT,
+                sequence: nextSequence(),
+                createdAtTimestamp: now,
+                content: structuredClone(content),
+                ...selector,
+            };
+            jobs.set(job.id, job);
+            notify();
+            return cloneJob(job);
+        },
+        async findDraftJobByFormType(formType) {
+            const normalizedFormType = String(formType || '').trim();
+            for (const job of jobs.values()) {
+                if (job.status !== JobStatus.DRAFT)
+                    continue;
+                if (inferFormType(job.content) === normalizedFormType) {
+                    return cloneJob(job);
+                }
+            }
+            return null;
+        },
+        async createOrUpdateDraftJob(content, selector) {
+            const formType = inferFormType(content);
+            const existing = formType ? await this.findDraftJobByFormType(formType) : null;
+            if (!existing) {
+                return this.createJob(content, selector);
+            }
+            const current = jobs.get(existing.id);
+            if (!current) {
+                return this.createJob(content, selector);
+            }
+            const updated = {
+                ...current,
+                ...selector,
+                thid: String(content?.thid || '').trim() || current.thid,
+                content: structuredClone(content),
+                previousSequence: current.sequence,
+                sequence: nextSequence(),
+            };
+            jobs.set(updated.id, updated);
+            notify();
+            return cloneJob(updated);
+        },
+        async sync() { },
+        async queryJobs(query) {
+            const filtered = [...jobs.values()].filter(job => matchesQuery(job, query));
+            if (query.orderBy) {
+                const { attribute, direction } = query.orderBy;
+                filtered.sort((left, right) => {
+                    const a = left[attribute];
+                    const b = right[attribute];
+                    if (a === b)
+                        return 0;
+                    const cmp = a > b ? 1 : -1;
+                    return direction === 'desc' ? -cmp : cmp;
+                });
+            }
+            const offset = Math.max(0, Number(query.offset || 0));
+            const limit = query.limit == null ? filtered.length : Math.max(0, Number(query.limit));
+            return filtered.slice(offset, offset + limit).map(cloneJob);
+        },
+        async submitJob(job) {
+            const current = jobs.get(job.id);
+            if (!current) {
+                throw new Error(`JobManager in-memory store cannot submit unknown job '${job.id}'.`);
+            }
+            jobs.set(job.id, {
+                ...current,
+                status: JobStatus.SENT,
+                previousSequence: current.sequence,
+                sequence: nextSequence(),
+            });
+            notify();
+        },
+        async sealJobWithToken(job) {
+            return job;
+        },
+        async getJobResponseByThid(thid) {
+            for (const job of jobs.values()) {
+                if (job.thid === thid && job.responseMessageId) {
+                    return {
+                        id: job.responseMessageId,
+                        thid,
+                    };
+                }
+            }
+            return null;
+        },
+        generateId() {
+            return createRuntimeUuid();
+        },
+    };
+}
+/**
+ * Requires one backend profile-runtime method from one runtime client.
+ */
+export function requireBackendProfileRuntimeMethod(client, method) {
+    const candidate = client[method];
+    if (typeof candidate !== 'function') {
+        throw new Error(`BackendProfileRuntimeClient does not implement '${String(method)}'.`);
+    }
+    return candidate.bind(client);
+}
+/**
+ * Canonical backend helper for loading one actor profile after authentication.
+ */
+export async function loadBackendProfile(client, input) {
+    return requireBackendProfileRuntimeMethod(client, 'loadProfile')(input);
+}
+/**
+ * Canonical backend helper for closing one loaded actor profile and clearing
+ * runtime-owned in-memory state.
+ */
+export async function closeBackendProfile(client, profileKey) {
+    return requireBackendProfileRuntimeMethod(client, 'closeProfile')(profileKey);
+}
+/**
+ * Canonical backend helper for registering one trusted device/runtime context.
+ */
+export async function registerBackendTrustedDevice(client, input) {
+    return requireBackendProfileRuntimeMethod(client, 'registerTrustedDevice')(input);
+}
+/**
+ * Canonical backend helper for connecting one actor profile to one subject
+ * index after the profile is already loaded.
+ */
+export async function connectBackendToSubjectIndex(client, input) {
+    return requireBackendProfileRuntimeMethod(client, 'connectToSubjectIndex')(input);
+}
+/**
+ * Canonical backend helper for reading one subject index composition after the
+ * relationship is already established.
+ */
+export async function getBackendSubjectIndexComposition(client, input) {
+    return requireBackendProfileRuntimeMethod(client, 'getSubjectIndexComposition')(input);
+}
+/**
+ * Returns one materialized backend actor session by actor kind.
+ *
+ * Backend callers should use this instead of scanning `actorSessions` manually.
+ */
+export function requireBackendActorSession(profile, actorKind) {
+    const session = profile.actorSessions.find(candidate => candidate.actorKind === actorKind);
+    if (!session) {
+        throw new Error(`Loaded backend profile does not expose actor kind '${actorKind}'.`);
+    }
+    return session;
+}
+/**
+ * Returns the individual-controller session from one loaded backend profile.
+ *
+ * This helper is the first concrete bridge from the generic backend runtime to
+ * the current individual bootstrap/index use case.
+ */
+export function requireBackendIndividualControllerSession(profile) {
+    return requireBackendActorSession(profile, ActorKinds.IndividualController);
+}
+/**
+ * Materializes the individual-controller facade directly from one loaded
+ * backend profile.
+ */
+export function requireBackendIndividualControllerSdk(profile) {
+    return requireBackendIndividualControllerSession(profile).asIndividualController();
+}
+/**
+ * Returns the organization-controller session from one loaded backend profile.
+ */
+export function requireBackendOrganizationControllerSession(profile) {
+    return requireBackendActorSession(profile, ActorKinds.OrganizationController);
+}
+/**
+ * Materializes the organization-controller facade directly from one loaded
+ * backend profile.
+ */
+export function requireBackendOrganizationControllerSdk(profile) {
+    return requireBackendOrganizationControllerSession(profile).asOrganizationController();
+}
+/**
+ * Returns the professional session from one loaded backend profile.
+ */
+export function requireBackendProfessionalSession(profile) {
+    return requireBackendActorSession(profile, ActorKinds.Professional);
+}
+/**
+ * Materializes the professional facade directly from one loaded backend
+ * profile.
+ */
+export function requireBackendProfessionalSdk(profile) {
+    return requireBackendProfessionalSession(profile).asProfessional();
+}
+/**
+ * Loads one backend profile and resolves the individual-controller session in
+ * one step.
+ *
+ * This is the first pragmatic use-case helper on top of the generic backend
+ * profile runtime, because the current stable CORE bootstrap baseline starts
+ * from the individual-controller flow.
+ */
+export async function loadBackendIndividualControllerProfile(client, input) {
+    const profile = await loadBackendProfile(client, input);
+    const session = requireBackendIndividualControllerSession(profile);
+    return {
+        profile,
+        session,
+        sdk: session.asIndividualController(),
+    };
+}
+/**
+ * Loads one backend profile and resolves the organization-controller session in
+ * one step.
+ */
+export async function loadBackendOrganizationControllerProfile(client, input) {
+    const profile = await loadBackendProfile(client, input);
+    const session = requireBackendOrganizationControllerSession(profile);
+    return {
+        profile,
+        session,
+        sdk: session.asOrganizationController(),
+    };
+}
+/**
+ * Loads one backend profile and resolves the professional session in one step.
+ */
+export async function loadBackendProfessionalProfile(client, input) {
+    const profile = await loadBackendProfile(client, input);
+    const session = requireBackendProfessionalSession(profile);
+    return {
+        profile,
+        session,
+        sdk: session.asProfessional(),
+    };
+}
+function createRuntimeUuid() {
+    const fromCrypto = globalThis.crypto?.randomUUID?.();
+    if (fromCrypto) {
+        return fromCrypto;
+    }
+    return `fallback-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}

package/dist/consent-claim-helpers.d.ts

@@ -1,4 +1,5 @@
 /**
  * Node runtime re-export of canonical consent claim helpers.
  */
-export { addActorIdentifierList, addActorRoleList, addActors, addCategories, addCategoryList, addClaimValues, addPurposeList, addPurposes, addRoles, addSections, getActorIdentifierList, getActorRoleList, getActors, getCategories, getCategoryList, getClaimValues, getConsentDate, getConsentIdentifier, getConsentPeriodEnd, getConsentPeriodStart, getPurposeList, getPurposes, getRoles, getSections, setActorIdentifierList, setActorRoleList, setActors, setCategories, setCategoryList, setClaimValues, setConsentDate, setConsentIdentifier, setConsentPeriodEnd, setConsentPeriodStart, setPurposeList, setPurposes, setRoles, setSections, type ConsentInteroperableClaims, } from 'gdc-sdk-core-ts';
+export { addActorIdentifierList, addActorRoleList, addActors, addCategories, addCategoryList, addClaimValues, addPurposeList, addPurposes, addRoles, addSections, getActorIdentifierList, getActorRoleList, getActors, getCategories, getCategoryList, getClaimValues, getConsentDate, getConsentIdentifier, getConsentPeriodEnd, getConsentPeriodStart, getPurposeList, getPurposes, getRoles, getSections, setActorIdentifierList, setActorRoleList, setActors, setCategories, setCategoryList, setClaimValues, setConsentDate, setConsentIdentifier, setConsentPeriodEnd, setConsentPeriodStart, setPurposeList, setPurposes, setRoles, setSections, } from 'gdc-sdk-core-ts';
+export type { ConsentInteroperableClaims, } from 'gdc-sdk-core-ts';

package/dist/family-organization-registration.d.ts

@@ -0,0 +1,40 @@
+import type { FamilyOrganizationSummary } from 'gdc-common-utils-ts/utils/family-organization-summary';
+import type { RouteContext } from './individual-onboarding.js';
+import { type IndividualOrganizationStartResult } from './individual-start.js';
+import { type FamilyOrganizationSearchInput } from './family-organization-search.js';
+import type { PollOptions, SubmitAndPollResult } from './orchestration/client-port.js';
+export type EnsureFamilyOrganizationRegistrationInput = FamilyOrganizationSearchInput & Readonly<{
+    controllerEmail?: string;
+    controllerRole?: string;
+    serviceProviderDid?: string;
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    additionalClaims?: Record<string, unknown>;
+}>;
+export type EnsureFamilyOrganizationRegistrationResult = Readonly<{
+    status: 'already_exists' | 'resume_required' | 'new_created';
+    summary?: FamilyOrganizationSummary;
+    started?: IndividualOrganizationStartResult;
+}>;
+type EnsureFamilyOrganizationRegistrationDeps = {
+    routeCtx: RouteContext;
+    input: EnsureFamilyOrganizationRegistrationInput;
+    defaultTimeoutMs?: number;
+    defaultIntervalMs?: number;
+    individualFamilyOrganizationSearchPath: (ctx: RouteContext) => string;
+    individualFamilyOrganizationSearchPollPath: (ctx: RouteContext) => string;
+    individualFamilyOrganizationBatchPath: (ctx: RouteContext) => string;
+    individualFamilyOrganizationPollPath: (ctx: RouteContext) => string;
+    submitAndPoll: (submitPath: string, pollPath: string, payload: {
+        thid?: string;
+    } & Record<string, unknown>, options?: PollOptions) => Promise<SubmitAndPollResult>;
+};
+/**
+ * High-level controller orchestration for phone-first onboarding channels:
+ * - first search whether the family/individual registration already exists
+ * - if it exists, return the normalized summary
+ * - otherwise start the bootstrap flow using the same business input
+ */
+export declare function ensureFamilyOrganizationRegistrationWithDeps(deps: EnsureFamilyOrganizationRegistrationDeps): Promise<EnsureFamilyOrganizationRegistrationResult>;
+export {};

package/dist/family-organization-registration.js

@@ -0,0 +1,54 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { startIndividualOrganizationWithDeps, } from './individual-start.js';
+import { searchFamilyOrganizationWithDeps, } from './family-organization-search.js';
+import { extractOfferIdFromResponseBody, extractOfferPreviewFromResponseBody } from './order-offer-summary.js';
+/**
+ * High-level controller orchestration for phone-first onboarding channels:
+ * - first search whether the family/individual registration already exists
+ * - if it exists, return the normalized summary
+ * - otherwise start the bootstrap flow using the same business input
+ */
+export async function ensureFamilyOrganizationRegistrationWithDeps(deps) {
+    const summary = await searchFamilyOrganizationWithDeps({
+        routeCtx: deps.routeCtx,
+        input: deps.input,
+        defaultTimeoutMs: deps.defaultTimeoutMs,
+        defaultIntervalMs: deps.defaultIntervalMs,
+        individualFamilyOrganizationSearchPath: deps.individualFamilyOrganizationSearchPath,
+        individualFamilyOrganizationSearchPollPath: deps.individualFamilyOrganizationSearchPollPath,
+        submitAndPoll: deps.submitAndPoll,
+    });
+    if (summary?.status === 'already_exists' || summary?.status === 'resume_required') {
+        return {
+            status: summary.status,
+            summary,
+        };
+    }
+    const started = await startIndividualOrganizationWithDeps({
+        input: {
+            serviceProviderDid: deps.input.serviceProviderDid,
+            tenantId: deps.input.tenantId,
+            jurisdiction: deps.input.jurisdiction,
+            sector: deps.input.sector,
+            alternateName: deps.input.usualname,
+            controllerEmail: deps.input.controllerEmail,
+            controllerTelephone: deps.input.controllerPhone,
+            controllerRole: deps.input.controllerRole,
+            additionalClaims: deps.input.additionalClaims,
+            timeoutSeconds: deps.input.timeoutSeconds,
+            intervalSeconds: deps.input.intervalSeconds,
+        },
+        routeCtx: deps.routeCtx,
+        defaultTimeoutMs: deps.defaultTimeoutMs,
+        defaultIntervalMs: deps.defaultIntervalMs,
+        individualFamilyOrganizationBatchPath: deps.individualFamilyOrganizationBatchPath,
+        individualFamilyOrganizationPollPath: deps.individualFamilyOrganizationPollPath,
+        submitAndPoll: deps.submitAndPoll,
+        getOfferIdFromResponse: (result) => extractOfferIdFromResponseBody(result.poll.body),
+        getOfferPreviewFromResponse: (result) => extractOfferPreviewFromResponseBody(result.poll.body),
+    });
+    return {
+        status: 'new_created',
+        started,
+    };
+}

package/dist/family-organization-search.d.ts

@@ -0,0 +1,30 @@
+import { type FamilyOrganizationSummary } from 'gdc-common-utils-ts/utils/family-organization-summary';
+import type { PollOptions, SubmitAndPollResult } from './orchestration/client-port.js';
+import type { RouteContext } from './individual-onboarding.js';
+export type FamilyOrganizationSearchInput = Readonly<{
+    controllerPhone: string;
+    usualname: string;
+    birthDate?: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+}>;
+type SearchFamilyOrganizationWithDeps = {
+    routeCtx: RouteContext;
+    input: FamilyOrganizationSearchInput;
+    defaultTimeoutMs?: number;
+    defaultIntervalMs?: number;
+    individualFamilyOrganizationSearchPath: (ctx: RouteContext) => string;
+    individualFamilyOrganizationSearchPollPath: (ctx: RouteContext) => string;
+    submitAndPoll: (submitPath: string, pollPath: string, payload: {
+        thid?: string;
+    } & Record<string, unknown>, options?: PollOptions) => Promise<SubmitAndPollResult>;
+};
+/**
+ * Searches one existing family/individual organization registration by the
+ * current phone-first business key used by UHC/UNID channel flows.
+ *
+ * Returns one normalized summary when the registration exists, otherwise
+ * `null`.
+ */
+export declare function searchFamilyOrganizationWithDeps(deps: SearchFamilyOrganizationWithDeps): Promise<FamilyOrganizationSummary | null>;
+export {};

package/dist/family-organization-search.js

@@ -0,0 +1,59 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { readFamilyOrganizationSummaryFromResponseBody, } from 'gdc-common-utils-ts/utils/family-organization-summary';
+import { ClaimsOrganizationSchemaorg, ClaimsServiceSchemaorg } from 'gdc-common-utils-ts/constants';
+import { resolvePollOptionsFromSeconds } from './poll-options.js';
+/**
+ * Searches one existing family/individual organization registration by the
+ * current phone-first business key used by UHC/UNID channel flows.
+ *
+ * Returns one normalized summary when the registration exists, otherwise
+ * `null`.
+ */
+export async function searchFamilyOrganizationWithDeps(deps) {
+    const controllerPhone = String(deps.input.controllerPhone || '').trim();
+    const usualname = String(deps.input.usualname || '').trim();
+    const birthDate = String(deps.input.birthDate || '').trim();
+    if (!controllerPhone) {
+        throw new Error('searchFamilyOrganization requires controllerPhone.');
+    }
+    if (!usualname) {
+        throw new Error('searchFamilyOrganization requires usualname.');
+    }
+    const claims = {
+        '@context': 'org.schema',
+        [ClaimsOrganizationSchemaorg.ownerTelephone]: controllerPhone,
+        [ClaimsOrganizationSchemaorg.alternateName]: usualname,
+        [ClaimsServiceSchemaorg.category]: deps.routeCtx.sector,
+        ...(birthDate ? { 'org.schema.Organization.foundingDate': birthDate } : {}),
+    };
+    const payload = {
+        jti: `jti-${createRuntimeUuid()}`,
+        thid: `family-search-${createRuntimeUuid()}`,
+        iss: deps.routeCtx.tenantId,
+        aud: deps.routeCtx.tenantId,
+        type: 'application/api+json',
+        body: {
+            data: [{
+                    type: 'Family-search-v1.0',
+                    meta: { claims },
+                    resource: { meta: { claims } },
+                }],
+        },
+    };
+    const pollOptions = resolvePollOptionsFromSeconds(deps.input.timeoutSeconds, deps.input.intervalSeconds, {
+        timeoutMs: deps.defaultTimeoutMs,
+        intervalMs: deps.defaultIntervalMs,
+    });
+    const result = await deps.submitAndPoll(deps.individualFamilyOrganizationSearchPath(deps.routeCtx), deps.individualFamilyOrganizationSearchPollPath(deps.routeCtx), payload, pollOptions);
+    if (result.poll.status !== 200) {
+        return null;
+    }
+    return readFamilyOrganizationSummaryFromResponseBody(result.poll.body);
+}
+function createRuntimeUuid() {
+    const fromCrypto = globalThis.crypto?.randomUUID?.();
+    if (fromCrypto) {
+        return fromCrypto;
+    }
+    return `fallback-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}