sos-sdk-core-ts 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## Unreleased
+
+- Pin the first registry release to `uhc-sdk-core-ts@0.6.0` so SOSChain
+  consumers can remove the historical vendored package from staging builds.
+
+## 0.1.5
+
+- Add the short-lived `incident-reporter` evidence relationship used when a
+  verified person scans an SOSChain/UHC/VetChain card at an incident without
+  claiming to be the subject's guardian, controller or professional.
+
+## 0.1.4
+
+- Add the deliberate public deterministic SHA3-384/CID target hash used by
+  smart contracts to return an existing Place or vehicle instead of duplicating it.
+
+## 0.1.3
+
+- Add flat claims for UHC/VetChain card associations to canonical SOSChain
+  Place or vehicle identities and explicit created/existing match results.
+
+## 0.1.2
+
+- Replace premature FHIR resource objects with canonical flat
+  `resource.meta.claims` contracts using kebab-case FHIR claim names.
+
+## 0.1.1
+
+- Add fail-closed emergency authorization evidence and regional/local delivery target contracts.
+- Name emergency groups explicitly.
+
+## 0.1.0
+
+- Add opaque SOSChain emergency-group claims.
+- Add the FHIR R5 `ServiceRequest` projection for group assistance.

package/README.md

@@ -0,0 +1,31 @@
+# SOSChain SDK Core
+
+Runtime-neutral SOSChain extension of `uhc-sdk-core-ts`.
+
+It consumes the exact published `uhc-sdk-core-ts` contract. Git, workspace,
+vendored and `file:` dependencies are forbidden in committed or deployed
+dependency state.
+
+The emergency-group contract treats `emergencyGroupId`, `subjectId` and
+`callerId` as opaque business identifiers. A group assistance request is one
+flat `ServiceRequest.*` claims under `resource.meta.claims`. A FHIR R5, R6 or
+other resource is projected only at an integration boundary.
+
+Groups are named collections. A scanned card is attached to one selected group
+before that group's identifiers are projected into a single service request.
+
+`authorizeSoschainEmergencyAction` separately checks trusted evidence for every
+member and for `sos:call` or `sos:request`. Identity verification alone never
+grants an emergency capability. Regional/local delivery is represented by
+`SoschainEmergencyDeliveryTarget`; transport and tenant routing stay outside FHIR.
+The `incident-reporter` relationship represents a short-lived grant issued by
+a trusted scan resolver to an already verified person at the scene; it does
+not imply guardianship, control or professional status.
+
+`buildSoschainPlaceCardAssociationClaims` records a UHC/VetChain card link to
+a canonical SOSChain Place or vehicle without merging either identity.
+
+```bash
+npm install
+npm run check
+```

package/dist/emergency-authorization.d.ts

@@ -0,0 +1,31 @@
+export type SoschainEmergencyCapability = 'sos:call' | 'sos:request';
+export type SoschainEvidenceDomain = 'SOS' | 'Health' | 'TrainingAndEducation';
+/** A verified evidence reference; the source VC/PDF stays outside call and audit logs. */
+export type SoschainEmergencyAuthorizationEvidence = Readonly<{
+    evidenceId: string;
+    issuerId: string;
+    holderId: string;
+    subjectIds: readonly string[];
+    capabilities: readonly SoschainEmergencyCapability[];
+    domains: readonly SoschainEvidenceDomain[];
+    relationship: 'self' | 'guardian' | 'professional' | 'institution' | 'incident-reporter';
+    verifiedAt: string;
+    validUntil?: string;
+}>;
+export type SoschainEmergencyDeliveryTarget = Readonly<{
+    tenantId: string;
+    jurisdiction: string;
+    locality?: string;
+    endpointId: string;
+}>;
+/**
+ * Requires current trusted evidence for every affected subject and capability.
+ * Identifier syntax and the legal meaning of each issuer remain policy concerns.
+ */
+export declare function authorizeSoschainEmergencyAction(input: Readonly<{
+    callerId: string;
+    memberSubjectIds: readonly string[];
+    capability: SoschainEmergencyCapability;
+    evidence: readonly SoschainEmergencyAuthorizationEvidence[];
+    now?: string;
+}>): readonly string[];

package/dist/emergency-authorization.js

@@ -0,0 +1,19 @@
+/**
+ * Requires current trusted evidence for every affected subject and capability.
+ * Identifier syntax and the legal meaning of each issuer remain policy concerns.
+ */
+export function authorizeSoschainEmergencyAction(input) {
+    const at = Date.parse(input.now ?? new Date().toISOString());
+    const evidenceIds = new Set();
+    for (const subjectId of input.memberSubjectIds) {
+        const accepted = input.evidence.find((item) => item.holderId === input.callerId &&
+            item.subjectIds.includes(subjectId) &&
+            item.capabilities.includes(input.capability) &&
+            Number.isFinite(Date.parse(item.verifiedAt)) && Date.parse(item.verifiedAt) <= at &&
+            (!item.validUntil || Date.parse(item.validUntil) >= at));
+        if (!accepted)
+            throw new Error(`emergency_authorization_evidence_required:${subjectId}:${input.capability}`);
+        evidenceIds.add(accepted.evidenceId);
+    }
+    return [...evidenceIds];
+}

package/dist/emergency-group.d.ts

@@ -0,0 +1,46 @@
+export declare const SOSCHAIN_FHIR_CLAIMS_CONTEXT: "org.hl7.fhir.api";
+export declare const SOSCHAIN_EMERGENCY_ASSISTANCE_CODE_SYSTEM = "https://soschain.org/fhir/CodeSystem/emergency-assistance";
+/** Canonical claims-first group record stored under resource.meta.claims. */
+export type SoschainEmergencyGroupClaims = Readonly<{
+    '@context': typeof SOSCHAIN_FHIR_CLAIMS_CONTEXT;
+    'Group.identifier': string;
+    'Group.name': string;
+    'Group.member-subject': readonly string[];
+    'Group.soschain-caller': string;
+    'Group.period-start': string;
+}>;
+/** Canonical claims-first request; FHIR version projection happens later. */
+export type SoschainEmergencyServiceRequestClaims = Readonly<{
+    '@context': typeof SOSCHAIN_FHIR_CLAIMS_CONTEXT;
+    'ServiceRequest.identifier': string;
+    'ServiceRequest.status': 'active';
+    'ServiceRequest.intent': 'order';
+    'ServiceRequest.code': string;
+    'ServiceRequest.code-system': typeof SOSCHAIN_EMERGENCY_ASSISTANCE_CODE_SYSTEM;
+    'ServiceRequest.code-display'?: string;
+    'ServiceRequest.subject': string;
+    'ServiceRequest.subject-type': 'Group';
+    'ServiceRequest.requester': string;
+    'ServiceRequest.authored-on': string;
+    'ServiceRequest.soschain-member-subject': readonly string[];
+}>;
+/** Builds flat, version-neutral FHIR claims without interpreting identifier syntax. */
+export declare function buildSoschainEmergencyGroupClaims(input: Readonly<{
+    emergencyGroupId: string;
+    displayName: string;
+    memberSubjectIds: readonly string[];
+    callerId: string;
+    createdAt?: string;
+}>): SoschainEmergencyGroupClaims;
+/**
+ * Builds one flat ServiceRequest claim set for all members of one emergency
+ * group. It deliberately does not construct a FHIR R5/R6 resource.
+ */
+export declare function buildSoschainEmergencyServiceRequestClaims(input: Readonly<{
+    requestId: string;
+    groupClaims: SoschainEmergencyGroupClaims;
+    assistanceCode?: string;
+    assistanceDisplay?: string;
+    authoredOn?: string;
+}>): SoschainEmergencyServiceRequestClaims;
+export declare function readSoschainEmergencySubjectIds(claims: SoschainEmergencyServiceRequestClaims): readonly string[];

package/dist/emergency-group.js

@@ -0,0 +1,48 @@
+export const SOSCHAIN_FHIR_CLAIMS_CONTEXT = 'org.hl7.fhir.api';
+export const SOSCHAIN_EMERGENCY_ASSISTANCE_CODE_SYSTEM = 'https://soschain.org/fhir/CodeSystem/emergency-assistance';
+function requiredIdentifier(value, name) {
+    const normalized = String(value).trim();
+    if (!normalized)
+        throw new TypeError(`${name} is required.`);
+    return normalized;
+}
+function uniqueIdentifiers(values) {
+    const identifiers = [...new Set(values.map((value) => requiredIdentifier(value, 'memberSubjectId')))];
+    if (identifiers.length === 0)
+        throw new TypeError('At least one memberSubjectId is required.');
+    return identifiers;
+}
+/** Builds flat, version-neutral FHIR claims without interpreting identifier syntax. */
+export function buildSoschainEmergencyGroupClaims(input) {
+    return {
+        '@context': SOSCHAIN_FHIR_CLAIMS_CONTEXT,
+        'Group.identifier': requiredIdentifier(input.emergencyGroupId, 'emergencyGroupId'),
+        'Group.name': requiredIdentifier(input.displayName, 'displayName'),
+        'Group.member-subject': uniqueIdentifiers(input.memberSubjectIds),
+        'Group.soschain-caller': requiredIdentifier(input.callerId, 'callerId'),
+        'Group.period-start': input.createdAt ?? new Date().toISOString(),
+    };
+}
+/**
+ * Builds one flat ServiceRequest claim set for all members of one emergency
+ * group. It deliberately does not construct a FHIR R5/R6 resource.
+ */
+export function buildSoschainEmergencyServiceRequestClaims(input) {
+    return {
+        '@context': SOSCHAIN_FHIR_CLAIMS_CONTEXT,
+        'ServiceRequest.identifier': requiredIdentifier(input.requestId, 'requestId'),
+        'ServiceRequest.status': 'active',
+        'ServiceRequest.intent': 'order',
+        'ServiceRequest.code': input.assistanceCode?.trim() || 'emergency-assistance',
+        'ServiceRequest.code-system': SOSCHAIN_EMERGENCY_ASSISTANCE_CODE_SYSTEM,
+        ...(input.assistanceDisplay ? { 'ServiceRequest.code-display': input.assistanceDisplay } : {}),
+        'ServiceRequest.subject': input.groupClaims['Group.identifier'],
+        'ServiceRequest.subject-type': 'Group',
+        'ServiceRequest.requester': input.groupClaims['Group.soschain-caller'],
+        'ServiceRequest.authored-on': input.authoredOn ?? new Date().toISOString(),
+        'ServiceRequest.soschain-member-subject': uniqueIdentifiers(input.groupClaims['Group.member-subject']),
+    };
+}
+export function readSoschainEmergencySubjectIds(claims) {
+    return claims['ServiceRequest.soschain-member-subject'];
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/** SOSChain extends UHC without moving product-specific contracts into UHC. */
+export * from 'uhc-sdk-core-ts';
+export * from './emergency-group.js';
+export * from './emergency-authorization.js';
+export * from './place-card-association.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+/** SOSChain extends UHC without moving product-specific contracts into UHC. */
+export * from 'uhc-sdk-core-ts';
+export * from './emergency-group.js';
+export * from './emergency-authorization.js';
+export * from './place-card-association.js';

package/dist/place-card-association.d.ts

@@ -0,0 +1,35 @@
+import { SOSCHAIN_FHIR_CLAIMS_CONTEXT } from './emergency-group.js';
+export type SoschainAssociationTargetType = 'Place' | 'Vehicle';
+export type SoschainAssociationRole = 'controller' | 'occupant' | 'employee' | 'guardian';
+/** Flat association record stored under resource.meta.claims. */
+export type SoschainPlaceCardAssociationClaims = Readonly<{
+    '@context': typeof SOSCHAIN_FHIR_CLAIMS_CONTEXT;
+    'Basic.identifier': string;
+    'Basic.code': 'soschain-card-target-association';
+    'Basic.subject': string;
+    'Basic.soschain-target': string;
+    'Basic.soschain-target-hash': string;
+    'Basic.soschain-target-type': SoschainAssociationTargetType;
+    'Basic.soschain-role': SoschainAssociationRole;
+    'Basic.period-start': string;
+}>;
+export type SoschainCanonicalTargetMatch = Readonly<{
+    status: 'created' | 'existing';
+    canonicalTargetId: string;
+    targetType: SoschainAssociationTargetType;
+}>;
+export declare function buildSoschainPlaceCardAssociationClaims(input: Readonly<{
+    associationId: string;
+    cardId: string;
+    canonicalTargetId: string;
+    canonicalTargetHash: string;
+    targetType: SoschainAssociationTargetType;
+    role: SoschainAssociationRole;
+    createdAt?: string;
+}>): SoschainPlaceCardAssociationClaims;
+/** Public deterministic SHA3-384/CID lookup key for smart-contract deduplication. */
+export declare function buildSoschainCanonicalTargetHash(input: Readonly<{
+    targetType: SoschainAssociationTargetType;
+    countryCode: string;
+    canonicalValue: string;
+}>): string;

package/dist/place-card-association.js

@@ -0,0 +1,30 @@
+import { SOSCHAIN_FHIR_CLAIMS_CONTEXT } from './emergency-group.js';
+import { buildRawCidV1FromUtf8String } from 'gdc-common-utils-ts/utils/multiformat-profile';
+function required(value, name) {
+    const normalized = String(value).trim();
+    if (!normalized)
+        throw new TypeError(`${name} is required.`);
+    return normalized;
+}
+export function buildSoschainPlaceCardAssociationClaims(input) {
+    return {
+        '@context': SOSCHAIN_FHIR_CLAIMS_CONTEXT,
+        'Basic.identifier': required(input.associationId, 'associationId'),
+        'Basic.code': 'soschain-card-target-association',
+        'Basic.subject': required(input.cardId, 'cardId'),
+        'Basic.soschain-target': required(input.canonicalTargetId, 'canonicalTargetId'),
+        'Basic.soschain-target-hash': required(input.canonicalTargetHash, 'canonicalTargetHash'),
+        'Basic.soschain-target-type': input.targetType,
+        'Basic.soschain-role': input.role,
+        'Basic.period-start': input.createdAt ?? new Date().toISOString(),
+    };
+}
+/** Public deterministic SHA3-384/CID lookup key for smart-contract deduplication. */
+export function buildSoschainCanonicalTargetHash(input) {
+    const canonical = [
+        input.targetType,
+        required(input.countryCode, 'countryCode').toUpperCase(),
+        required(input.canonicalValue, 'canonicalValue').normalize('NFC').trim().replace(/\s+/g, ' ').toLowerCase(),
+    ].join('|');
+    return buildRawCidV1FromUtf8String(canonical);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "sos-sdk-core-ts",
+  "version": "0.1.5",
+  "description": "Runtime-neutral SOSChain contracts extending uhc-sdk-core-ts",
+  "license": "Apache-2.0",
+  "author": "Connecting Solution & Applications Ltd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fundacion-UNID/sos-sdk-core-ts.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./emergency-group": {
+      "types": "./dist/emergency-group.d.ts",
+      "default": "./dist/emergency-group.js"
+    },
+    "./emergency-authorization": {
+      "types": "./dist/emergency-authorization.d.ts",
+      "default": "./dist/emergency-authorization.js"
+    },
+    "./place-card-association": {
+      "types": "./dist/place-card-association.d.ts",
+      "default": "./dist/place-card-association.js"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "check": "npm run typecheck && npm test",
+    "prepack": "npm run check"
+  },
+  "dependencies": {
+    "gdc-common-utils-ts": "^2.3.28",
+    "uhc-sdk-core-ts": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.5.4"
+  }
+}