abdm-m2-care-context

name	abdm-m2-care-context
description	Integrate ABDM Milestone 2 - care context linking, record discovery, HIP data sharing, webhook handling, and ECDH encryption for pushing FHIR bundles to HIUs. Use when the user says "integrate M2", "link care context", "HIP", "share records", "hip_data_fetch webhook", "discovery", or is connecting a hospital/lab system that generates health records.

M2 — Care Context Linking & Data Sharing (HIP)

Prereq: auth working, patients have ABHA (M1). A care context = one logical record group (a visit, a lab test, an uploaded document).

Data custody: Option B is the only one available today

Option	How	Consequence
B. Client keeps data (default — plan around this)	Link without data	Must handle abha.hip_data_fetch webhook: build FHIR bundle on demand, ECDH-encrypt with the webhook's key material, push via Data On-Fetch API
A. Eka stores data	Pass base64 ABDM-compliant FHIR bundle in the data field of the Link API (or use the Upload API)	Eka auto-serves HIUs, no webhook/encryption — not an enabled option for most accounts today, don't offer it as a routine choice

Don't ask the user which option they want — build for B by default. Read references/ecdh-encryption.md and data-on-fetch.md. Only mention Option A if the client already knows it's enabled on their account.

Core flow (HIP-initiated linking)

POST /abdm/v1/care-contexts/link   (202 Accepted — async!)
headers: X-Pt-Id (Eka oid) | X-Partner-Pt-Id (client's patient ID) | X-Hip-Id
body: { abha_address, care_contexts: [{care_context_id, display, hi_type|hi_types, data?}] }
→ webhook abha.link_care_context: LINKED | ERRORED

If the client's account has more than one facility/HIP registered, ask which hip_id (and clinic, if their HIP has multiple linked NDHM clinics) this integration run's X-Hip-Id should use — don't assume a single facility. hi_type enum: OPConsultation, Prescription, DischargeSummary, DiagnosticReport, ImmunizationRecord, HealthDocumentRecord, WellnessRecord. Map the client's document types to these (ask if ambiguous — e.g. lab reports → DiagnosticReport).

Integration method: raw API, or the console's backend SDK

Ask which the client wants — don't default silently. Two real options:

• Raw REST APIs (documented above and in docs-map.md) — full control, works in any backend language.
• Backend SDK (per-language: Go/JavaScript/Java/Python) — e.g. Go's github.com/eka-care/eka-sdk-go (go get github.com/eka-care/eka-sdk-go, init via ekasdk.NewFromEnv() or explicit ekasdk.New(...)). Source note: the package and base init are now public (/SDKs/backend/go-sdk.md), but as of this writing that page only documents client.ABDM.Login(), .Registration(), .Profile() and says "more services will be added as they become available" — the care-context-specific method (e.g. client.ABDM.CareContexts().RespondToFetch(ctx, fhirBundle)) is still only confirmed via the client's console module page ("M2 · Care Context Linking and Data Sharing (HIP) — Backend SDK"), not the public docs yet. Always re-fetch /SDKs/backend/go-sdk.md (and the JS/Java/Python equivalents) before coding — it may have caught up — and fall back to asking the client for their console snippet if it hasn't. The SDK still doesn't build the FHIR bundle for you — that's always the abdm-fhir skill's job, SDK or not.

Discovery (patient pulls records from your facility)

Patient searches your facility from their PHR app → you receive discover_care_context webhook → respond with matching unlinked contexts → link-init/link-confirm handshake (user OTP). Fetch care-contexts/discover/introduction.md for the sequence. Requires matching patients by demographics — plan the matching query against the client's patient table (name+gender+YOB+mobile, be conservative to avoid leaking records).

Listing linked data (for doctor/PHR UI)

1. providers/providers.md → linked providers (hip_id each)
2. records/records.md → care contexts per provider

Integration blueprint

1. Webhook infrastructure first: one endpoint, e.g. POST /webhooks/eka, verifying Eka's signature, routing on event type (abha.link_care_context, abha.hip_data_fetch, abha.discover_care_context, ...). For local dev use a tunnel (ngrok/cloudflared). ABDM event webhooks have no self-service registration API as of this writing (Eka's POST /notification/v1/connect/webhook/subscriptions API is scoped to appointment/prescription/receipt events only, not ABDM events) — ask the client for their public webhook URL as soon as it's live, then relay it to Eka console/support on their behalf; don't leave this as a vague "register it later" step.
2. Trigger points in the HIS: hook care-context linking into the client's "visit closed" / "report finalized" event. Ask where that lives in their codebase.
3. FHIR construction: use the abdm-fhir skill to map the client's data model to ABDM FHIR bundles.
4. State table: care_context_links(care_context_id, abha_address, status, hi_type, linked_at, error) — reconcile on webhook.
5. ECDH encryption util + on-fetch responder (idempotent; ABDM retries) — generate the key material yourself in code per references/ecdh-encryption.md, don't ask the user to produce it.

Fetch each endpoint's .md page before coding (paths: ../abdm-overview/references/docs-map.md).

Test before done

Link with data / without data, webhook LINKED + ERRORED paths, discovery round-trip, duplicate care_context_id, and (option B) a full consented HIU fetch in sandbox.