uhc-sdk-core-ts

Development and releases follow the mandatory local-first TDD and release contract.

Extension package for UHC/UNID-specific SDK and GW behavior that should not live in CORE.

Read first:

1. gdc-common-utils-ts/docs/101-BFF_AND_CHANNEL_MESSAGE_FLOW.md
2. gdc-common-utils-ts/docs/101-COMMUNICATION_LAYERING.md
3. docs/UHC_OWN_PIECES_AND_STORIES.md
4. docs/KEY_CUSTODY_AND_PRODUCT_BOUNDARIES.md

This package is intended to sit on top of both:

• gdc-common-utils-ts
• gdc-sdk-core-ts

and host:

• phone-first consent target extensions
• notification-oriented examples and helpers
• UHC/UNID-specific permission and communication fixtures
• extension-only tests that should not be part of CORE shared contracts

Current scope:

• re-export selected CORE identity contracts from gdc-common-utils-ts
• re-export runtime-neutral SDK contracts from gdc-sdk-core-ts
• define UHC extension target kinds
• define the UHC card layout and public did:web route for card/uhc/<subjectType>/<subjectId>
• provide starter examples for notification and phone-based permission requests
• define extension-only missing-permission request payloads for controller UX

This package is the intended home for extension tests that validate UHC/UNID semantics without polluting gdc-common-utils-ts.

For the MVP it also exposes analyzeBundleChangesResponse(...) from src/to-be-moved/. That tree is deliberately split by its future GDC package owner, so portals can test the contract now and the later extraction is a mechanical move. The helper receives only the submitted changes Bundle and its GW response; application display state remains outside the SDK.

It is also the runtime-neutral base that should be consumed by:

• uhc-sdk-node-ts
• uhc-sdk-front-ts

so that UHC apps can extend the GDC SDK family without duplicating extension fixtures in every runtime package.

What belongs here

• UHC/UNID-only consent target kinds:
  • phone
  • organization-domain
  • push-channel
• extension-only permission request payloads
• SOSChain Place, device-binding, proximity-event, and emergency-channel contracts
• examples and tests for notification-driven consent flows
• SDK-side helpers that sit on top of:
  • gdc-common-utils-ts
  • gdc-sdk-core-ts
• future veterinary segmentation taxonomy and related extension semantics when they should not live in shared packages

What does not belong here

• CORE shared contracts
• CORE DID/service resolution
• CORE bootstrap payloads
• generic SMART/consent matrix logic that every deployment should share

Those pieces must remain in:

• gdc-common-utils-ts
• gdc-sdk-core-ts

Repository boundary note:

• concrete veterinary network taxonomy should evolve here, not in gdc-common-utils-ts
• ICA docs may temporarily document only the initial animal onboarding domain
• finer taxonomy should be introduced here once the extension contract is ready

Current exports

• the complete hosted individual-member DID builder and identifier types from gdc-common-utils-ts
• all exports from gdc-sdk-core-ts
• UhcConsentTargetKinds
• createUhcConsentTargetDescriptor(...)
• createUhcMissingPermissionRequest(...)
• createUhcPhoneVerifyStartInput(...)
• createUhcPhoneVerifyConfirmInput(...)
• createUhcFamilyContactRegistrationInput(...)
• buildUhcCardDidWeb(...)
• buildUhcCardTextLines(...)
• buildUhcCardLayoutInches(...)
• EXAMPLE_UHC_PERMISSION_REQUEST_NOTIFICATION
• EXAMPLE_UHC_MISSING_PERMISSION_REQUEST
• EXAMPLE_UHC_PHONE_VERIFY_START_INPUT
• EXAMPLE_UHC_PHONE_VERIFY_CONFIRM_INPUT
• EXAMPLE_UHC_FAMILY_MULTI_EMAIL_REGISTRATION_INPUT
• EXAMPLE_UHC_FAMILY_MULTI_PHONE_REGISTRATION_INPUT
• EXAMPLE_UHC_VOICE_REMINDER_DEMO_CONTEXT
• ClaimsPlaceSchemaorg
• ClaimsEventSchemaorg
• ClaimsSoschainDeviceSchemaorg
• ClaimsSoschainIndividualProductSchemaorg
• buildSoschainPlaceClaims(...)
• buildSoschainDeviceClaims(...)
• buildSoschainIndividualProductClaims(...)
• createSoschainPlaceRegistrationInput(...)
• buildSoschainPlaceRegistrationClaims(...)
• createSoschainPlaceBeacon(...)
• encodeSoschainAudienceIdentifiers(...)
• decodeSoschainAudienceIdentifiers(...)
• resolveNearestSoschainPlace(...)
• selectSoschainEmergencyNotificationTargets(...)

The focused uhc-sdk-core-ts/soschain-location export is runtime-neutral and safe for portal, BFF, and mobile consumers. See docs/SOSCHAIN_LOCATION_MVP.md for the claims-first contract and end-to-end MVP flow.

The reminder demo context now exposes hostRegistryNetwork as the preferred name for the host onboarding network selector. hostRegistrySector remains as a legacy alias while UNID GW scripts finish migrating.

Current UHC Docs

• docs/reminder-permissions-integration-status.md
• docs/channel-invitation-and-relationship-pin-program.md
• docs/uhc-veterinary-voice-and-permissions-follow-up-task.md
• docs/subject-display-code-policy.md

Next Architecture Task

The next major reminder/refactor task is documented in:

• docs/reminder-orchestration-and-channel-dispatch-task.md
• docs/channel-invitation-and-relationship-pin-program.md

That task defines the target model for:

• reminder items
• reminder plans
• dispatch windows
• dispatch attempts
• reminder outcomes
• permission-aware multichannel orchestration

Pending

• move more UNID/UHC extension fixtures here from gateway tests
• add permission-evaluation examples for:
  • phone target
  • organization-domain target
  • push notification flows
• add controller-facing request retrieval helpers once the consent access matrix thread lands
• migrate UNID GW extension tests to consume these examples once the package has remote availability
• keep uhc-sdk-node-ts and uhc-sdk-front-ts as thin runtime bridges on top of this package, not as duplicate sources of truth
• execute the reminder orchestration and channel dispatch task documented under docs/
• lift stable invitation/channel-enrollment contracts into CORE once the shared shape is closed