Welshare shared library functions

This SDK contains provides functions, types, schemas and utilities to interact with Welshare's sovereign health data sharing protocol. It includes FHIR resource handling, Nillion integration, API clients, and validation schemas. If you're just looking for an easy way to submit data from your own frontend, the @welshare/react package might be a better fit. Use this SDK if you want to build infrastructure to manage, authenticate and profile users yourself. The bare minimum requirement is to support a signer function that users use to deterministically derive storage keypairs from their control wallets.

The package wraps Nillion's secretvaults / nuc / blindfold libraries. Some of which have server side dependencies (pino-pretty) that can create quirky side effects when running in browsers if not deliberately treeshaken. Make sure to not expose server facing features in this library (ie code that makes use of Nillion "standard" collections)

We're using tshy to build ESM compatible outputs. CommonJS is not supported.

You can find compiled API docs here: https://docs.welshare.app/sdk-docs/

Overview

Utilities

• Base64 encoding/decoding: base64urlEncode(), base64urlDecode(), base64urlDecodeUtf()
• Hex utilities: bytesToHex(), hexToBytes() (re-exported from viem)
• UUID generation: makeUid()

Authentication Tools

• JWT handling: createJWTForStorageKeys(), verifyJWT()
• Key derivation: deriveKey() (with types Context, KeyId, UserSecret)
• Storage keys: deriveApplicationKeypair(), deriveStorageKeypair(), verifyAuthProof()

FHIR Resources

• FHIR namespace (Fhir):
  • validateQuestionnaire() - Validate FHIR Questionnaire resources
  • validateQuestionnaireResponse() - Validate FHIR QuestionnaireResponse resources
  • wrapFhirResourceForNillion() - Wrap FHIR resources for Nillion insertion
  • fhirDateRegex, fhirDateTimeRegex, fhirBase64BinaryRegex - Validation regex patterns
• FHIR types: FhirCoding, FhirCodeableConcept, FhirQuantity, FhirSimpleQuantity, FhirRange, FhirRatio, FhirPeriod, FhirAttachment, FhirSampledData
• Standard codes (StandardCodes namespace) - FHIR standard code definitions. This is VERY helpful to refer to commonly used health conditions and observations and they frequently are found in user facing questionnaires.

Nillion Integration

• Nillion namespace (Nillion):
  • Keypair - Keypair class from @nillion/nuc (this will be replaced with a signer interface soon)
  • makeUserClient() - Create a SecretVault UserClient
  • summarizeUploadResults() - Processes an array of redundant "upload" result that's returned by cluster nodes to one single result
• Nillion types: CollectionType, NillionClusterConfig, NillionByNodeName, NillionDid, NillionUuid, BlindfoldFactoryConfig

Welshare API Client

This namespace contains helpers that talk to the Welshare root infrastructure. While user data is stored in owned collections that conceptually aren't directly under our control, the application data (e.g. questionnaire definitions) is stored on Nillion collections that we maintain.

• WelshareApi namespace:

  • fetchWelshareApp() - Fetches the AppRecord of a given applicationId
  • fetchDelegation() - users call this to request a delegation NUC that allows them to access to owned collections.
  • submitData() - A facade that helps submitting (questionnaire) data correctly. Fetches apps and delegations in the background, interpolates fields with client side knowledge, and pushes data to Nillion nodes.

• Environment configuration:

  • WELSHARE_API_ENVIRONMENT - Pre-configured environments (production, staging, preview, development)
  • resolveEnvironment() - Resolve environment configuration with optional overrides
  • WelshareApiEnvironment - Type definition for environment config

Validation Schemas

All schemas are exported as Zod schemas for validation:

• AppSchema - Application configuration
• QuestionnaireSchema - FHIR Questionnaire
• QuestionnaireResponseSchema - FHIR QuestionnaireResponse
• PatientSchema - root FHIR Patient data
• ObservationSchema - FHIR Observation
• ObservationHelpers - Helper functions for observations
• ConditionSchema - FHIR Condition
• ConditionHelpers - Helper functions for conditions
• BinaryFilesSchema - Binary files
• NotificationsSchema - Notifications

Types

• Session types: SessionKeyAuthMessage, AuthorizedSessionProof, SessionKeyData
• Validation types: InsertableSubmission, InterpolateSocials, ValidatableSchema

Schemas

Fhir Resources

as an example, we're storing a subset of Fhir HL7 R5 QuestionnaireResponses. See questionnaire-response.schema.json.

• A good json schema validation tester: https://www.jsonschemavalidator.net/
• more tools https://forgetoolbox.com/
• even more tools https://www.jsonforge.com/