From 66e896d70913e2cf23e950a6b114603591098069 Mon Sep 17 00:00:00 2001 From: Moenga Daniel Date: Fri, 14 Aug 2026 02:00:47 +0300 Subject: [PATCH 1/2] Document research evidence boundaries --- changelog.mdx | 6 +++ concepts/institutions.mdx | 2 +- docs.json | 4 ++ index.mdx | 4 +- research/evidence.mdx | 79 +++++++++++++++++++++++++++++++++++++++ sdks.mdx | 7 ++++ 6 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 research/evidence.mdx diff --git a/changelog.mdx b/changelog.mdx index 517b911..3de1074 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -6,6 +6,12 @@ rss: true Released API changes appear here. Product and website changes are on the [Heyrafiki changelog](https://heyrafiki.space/changelog). + +**Added** a [research and evidence guide](/research/evidence) connecting public statements to the OpenAPI contract, Assurance Graph, synthetic fixtures, deterministic runners and stated limitations. + +**Documented** First Light v2 as reproducible synthetic conformance evidence. It does not establish clinical validity, population effectiveness or a novelty claim. + + **Changed** the remote MCP server to the `2026-07-28` protocol contract, including stateless discovery, per-request capability metadata, transport header validation and structured completion results. diff --git a/concepts/institutions.mdx b/concepts/institutions.mdx index de7e4b3..ecc525d 100644 --- a/concepts/institutions.mdx +++ b/concepts/institutions.mdx @@ -9,7 +9,7 @@ Institutional integrations use versioned resources for Practitioner discovery, B Connect Coverage, eligibility, pre-authorization, Claims, remittance and reconciliation. - + Review authority, data minimization, audit evidence and controlled exchange boundaries. diff --git a/docs.json b/docs.json index 496c96e..bb55a6f 100644 --- a/docs.json +++ b/docs.json @@ -139,6 +139,10 @@ { "group": "Security and data governance", "pages": ["security/overview", "security/data-boundaries"] + }, + { + "group": "Research and evidence", + "pages": ["research/evidence"] } ] }, diff --git a/index.mdx b/index.mdx index 61c18dd..c021b9b 100644 --- a/index.mdx +++ b/index.mdx @@ -26,8 +26,8 @@ https://api.heyrafiki.space/v1 Review integration ownership, financial controls and the synthetic acceptance plan. - - Review authority boundaries, testing and protocol-bound access. + + Inspect authority boundaries, executable evidence and research limitations. diff --git a/research/evidence.mdx b/research/evidence.mdx new file mode 100644 index 0000000..6766c9d --- /dev/null +++ b/research/evidence.mdx @@ -0,0 +1,79 @@ +--- +title: "Research and evidence" +description: "Follow Heyrafiki statements to public contracts, executable evidence and explicit research limitations." +keywords: ["mental health research evidence", "reproducible conformance", "First Light", "Assurance Graph"] +--- + +Heyrafiki publishes the evidence that another team can inspect and run. The public path starts with a defined statement and ends with a versioned contract, synthetic fixture, expected result, deterministic runner and visible limitation. + +```mermaid +flowchart LR + Statement["Defined statement"] --> Contract["Versioned contract"] + Contract --> Fixture["Synthetic fixture"] + Fixture --> Expected["Expected result"] + Expected --> Runner["Deterministic runner"] + Runner --> Limitation["Stated limitation"] +``` + +## Public evidence authorities + +| Authority | What it owns | Inspect it | +| --- | --- | --- | +| Contract | The public REST surface and machine-readable Assurance Graph | [heyrafiki/contract](https://github.com/heyrafiki/contract) | +| Proving Ground | Deterministic conformance suites, fixtures and expected results | [heyrafiki/proving-ground](https://github.com/heyrafiki/proving-ground) | +| Docs | Integration guidance and the meaning of released public behavior | [heyrafiki/docs](https://github.com/heyrafiki/docs) | +| SDK repositories | Language-specific source maintained against the public contract | [SDK guide](/sdks) | + +The Platform implementation remains the authority for runtime behavior. Public repositories make contracts and selected evidence independently inspectable without becoming a second runtime authority. + +## First Light v2 + +First Light v2 tests longitudinal assessment conformance with a fixed synthetic cohort. The public pack contains 48 cases, knowledge-time and amendment scenarios, adverse boundaries, expected results and audit-completeness checks. + + + + Review the declared synthetic cohort, measures and interpretation boundary. + + + See which conclusions the benchmark includes and excludes. + + + Inspect the machine-readable version, assumptions and checks. + + + Read the generated results beside their limitations. + + + +Run the full public evidence repository: + +```bash +git clone https://github.com/heyrafiki/proving-ground.git +cd proving-ground +npm ci +npm test +``` + +## What the current evidence supports + +The public suites support claims about contract coverage, deterministic scoring, bitemporal replay, Consent-aware access boundaries, audit completeness and rejection of declared adversarial mutations. + +They do not establish: + +- clinical validity or diagnostic performance; +- effectiveness for a Kenyan or other real population; +- actuarial savings or health outcomes; +- safety under every production condition; +- novelty, patentability or scientific priority. + +Those conclusions require a separate protocol, appropriate approvals, licensed instruments, representative data, baseline methods, uncertainty estimates and expert review. + +## From architecture to a research result + +A research candidate is ready for formal evaluation only when its problem, assumptions, prior art, baseline, protocol, measures, data rights, failure implications and review owner are written down before outcome claims are made. + +The [Assurance Graph](/institutions/assurance-graph) provides the traceability layer. It connects public operations and controls to executable evidence. It is an architecture and conformance artifact, not evidence that the architecture is scientifically novel. + +## Reporting a mismatch + +If a public statement, contract, fixture or result disagrees with another authority, open an issue in the repository that owns the mismatched artifact. Security and privacy findings should follow the private process in the [Security overview](/security/overview). diff --git a/sdks.mdx b/sdks.mdx index c2fc9b1..6308f18 100644 --- a/sdks.mdx +++ b/sdks.mdx @@ -7,6 +7,13 @@ keywords: ["Heyrafiki SDK", "healthcare API clients", "insurance API", "Heyrafik Every SDK follows the same OpenAPI contract, authentication rules, idempotency requirements, error envelope and request identifiers. + + The current SDK and CLI release is source-only. Registry packages and + versioned GitHub Releases have not been published. Use the reviewed public + repositories and the build commands below until a release appears in the + owning repository. + + ## Choose a client | Client | Runtime | Primary use | From 6218e6cc1dc201af462d033eb30b36daf30a4061 Mon Sep 17 00:00:00 2001 From: Moenga Daniel Date: Fri, 14 Aug 2026 03:13:13 +0300 Subject: [PATCH 2/2] Make documentation audience-led and release-verifiable --- .gitignore | 1 + authentication.mdx | 1 + benefits.mdx | 1 + changelog.mdx | 9 +++- claims.mdx | 1 + concepts/capabilities.mdx | 1 + concepts/institutions.mdx | 19 ++++---- concepts/platform.mdx | 1 + docs.json | 10 +++-- environments.mdx | 1 + errors.mdx | 1 + index.mdx | 27 ++++++++---- insurance/acceptance-testing.mdx | 10 ++--- insurance/claim-valuation-timeline.mdx | 8 ++-- quickstart.mdx | 18 ++++++++ rate-limits.mdx | 1 + requests.mdx | 1 + research/evidence.mdx | 25 +++++++++-- resources.mdx | 25 ++++++++++- sandbox.mdx | 1 + scopes.mdx | 1 + scripts/check-docs.mjs | 61 +++++++++++++++++++++++++- sdks.mdx | 7 ++- security/data-boundaries.mdx | 1 + security/overview.mdx | 1 + style.css | 58 +++++++++++++++++++----- testing.mdx | 1 + versioning.mdx | 1 + webhooks.mdx | 1 + 29 files changed, 243 insertions(+), 51 deletions(-) diff --git a/.gitignore b/.gitignore index 1c2ba07..d7ea085 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ node_modules/ .mintlify/ +.playwright-cli/ .DS_Store diff --git a/authentication.mdx b/authentication.mdx index 0642684..2b7c129 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -1,6 +1,7 @@ --- title: "Authentication" description: "Authenticate Heyrafiki API requests with a secret key." +keywords: ["API authentication", "Bearer token", "Heyrafiki API key"] --- Authenticate with a secret key sent as a Bearer token. diff --git a/benefits.mdx b/benefits.mdx index aa838eb..94e18fc 100644 --- a/benefits.mdx +++ b/benefits.mdx @@ -1,6 +1,7 @@ --- title: "Benefits" description: "Check Cover and reserve an approved Session." +keywords: ["health insurance eligibility API", "pre-authorization API", "mental health Benefits"] --- The Benefit flow has two resources: diff --git a/changelog.mdx b/changelog.mdx index 3de1074..2b0289d 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -1,15 +1,22 @@ --- title: "API changelog" description: "Released changes to the Heyrafiki API." +keywords: ["Heyrafiki API changelog", "API releases", "OpenAPI changes"] rss: true --- Released API changes appear here. Product and website changes are on the [Heyrafiki changelog](https://heyrafiki.space/changelog). + +**Documented** the complete [API overview](/resources) as eight resource areas and 31 released operations. The generated endpoint reference and public contract remain the operation-level authorities. + + **Added** a [research and evidence guide](/research/evidence) connecting public statements to the OpenAPI contract, Assurance Graph, synthetic fixtures, deterministic runners and stated limitations. -**Documented** First Light v2 as reproducible synthetic conformance evidence. It does not establish clinical validity, population effectiveness or a novelty claim. +**Added** the Stage 1 Assurance Graph protocol manuscript, prior-art search record and independent reviewer packet. The candidate is evaluated against five progressively stronger baselines before results are published. + +**Documented** First Light v2 as reproducible synthetic conformance evidence. It does not establish clinical validity or population effectiveness. diff --git a/claims.mdx b/claims.mdx index 5221e55..1fe746f 100644 --- a/claims.mdx +++ b/claims.mdx @@ -1,6 +1,7 @@ --- title: "Claims and remittance" description: "Submit, review and reconcile covered Care." +keywords: ["health Claims API", "Claim adjudication", "remittance reconciliation"] --- Claims start from delivered Care, an eligible Benefit and approved service evidence. Amounts use the currency's minor unit. diff --git a/concepts/capabilities.mdx b/concepts/capabilities.mdx index 8900633..bc7551d 100644 --- a/concepts/capabilities.mdx +++ b/concepts/capabilities.mdx @@ -1,6 +1,7 @@ --- title: "Platform capabilities" description: "The resource families and contracts that make up the Heyrafiki Platform." +keywords: ["platform capabilities", "typed capabilities", "healthcare API architecture"] --- The public contract grows by capability. Generated endpoint pages remain the authority for callable operations. diff --git a/concepts/institutions.mdx b/concepts/institutions.mdx index ecc525d..4e57ac4 100644 --- a/concepts/institutions.mdx +++ b/concepts/institutions.mdx @@ -1,21 +1,22 @@ --- title: "Institutional integrations" description: "Connect Care, Cover, Claims and audit through governed contracts." +keywords: ["institutional healthcare integration", "payer API", "health data governance", "research integration"] --- Institutional integrations use versioned resources for Practitioner discovery, Bookings, Benefits, Claims and remittance. - + Connect Coverage, eligibility, pre-authorization, Claims, remittance and reconciliation. - + Review authority, data minimization, audit evidence and controlled exchange boundaries. - + Coordinate Care through purpose-bound Practitioner, Booking and Session capabilities. - + Use approved protocols, synthetic environments and versioned public contracts. @@ -50,19 +51,19 @@ Credential issuers remain authoritative for professional status. Payers remain a ## Five-role acceptance model - + Verify Coverage ingestion, eligibility, pre-authorization, Claim adjudication, remittance, Webhooks, retries and cross-tenant denial against the versioned contract. - + Recompute line and Claim identities, reconcile advice to independent settlement evidence, and preserve service, submission, adjudication and payment dates for governed analysis. - + Confirm that service evidence connects delivered Care to the covered workflow while Clinical Notes, Messages and private Session content remain outside the payer contract. - + Exercise Organization isolation, least-privilege scopes, synthetic-only test data, signature validation, stale-event rejection and minimum-necessary response fields. - + Retain the contract commit, owner map, request identifiers, idempotency evidence, negative-test results, policy versions, reconciliation evidence and activation decision. diff --git a/concepts/platform.mdx b/concepts/platform.mdx index 2439329..1b7758d 100644 --- a/concepts/platform.mdx +++ b/concepts/platform.mdx @@ -1,6 +1,7 @@ --- title: "Platform workflow" description: "How public resources connect Care, Cover, Claims and remittance." +keywords: ["healthcare platform workflow", "Care and Claims", "API workflow"] --- Heyrafiki connects Care and payment operations through shared resource identifiers and versioned contracts. diff --git a/docs.json b/docs.json index bb55a6f..59e0ba5 100644 --- a/docs.json +++ b/docs.json @@ -2,7 +2,7 @@ "$schema": "https://mintlify.com/docs.json", "theme": "mint", "name": "Heyrafiki", - "description": "The Heyrafiki API: authentication, errors and live resources.", + "description": "Reference and integration guidance for the Heyrafiki API, Sandbox, insurance and institutional workflows.", "styling": { "eyebrows": "breadcrumbs", "codeblocks": "dark" @@ -18,7 +18,7 @@ }, "colors": { "primary": "#184A34", - "light": "#2F9E68", + "light": "#56C995", "dark": "#3D7B5C" }, "appearance": { @@ -72,7 +72,11 @@ "prompt": "Search Heyrafiki Docs" }, "seo": { - "indexing": "navigable" + "indexing": "navigable", + "metatags": { + "canonical": "https://docs.heyrafiki.space", + "og:locale": "en_KE" + } }, "metadata": { "timestamp": true diff --git a/environments.mdx b/environments.mdx index 49cb8ea..844a771 100644 --- a/environments.mdx +++ b/environments.mdx @@ -1,6 +1,7 @@ --- title: "Environments" description: "Separate sandbox development from regulated production use." +keywords: ["API environments", "Sandbox", "production access"] --- Heyrafiki keys are bound to one environment. diff --git a/errors.mdx b/errors.mdx index 42d7256..1063091 100644 --- a/errors.mdx +++ b/errors.mdx @@ -1,6 +1,7 @@ --- title: "Errors" description: "HTTP status codes and the Heyrafiki error envelope." +keywords: ["API errors", "HTTP status codes", "error envelope"] --- Every API error returns the same envelope. diff --git a/index.mdx b/index.mdx index c021b9b..63a4a9f 100644 --- a/index.mdx +++ b/index.mdx @@ -17,17 +17,26 @@ https://api.heyrafiki.space/v1 Sandbox keys are issued to approved projects. Sandbox records are isolated from production and cannot be used for Care delivery, Benefits decisions or Claims. -## Choose a path +## Choose your path - - Authenticate, make a request and work through the sandbox. + + Make the first request, handle errors and build against the Sandbox. - - Review integration ownership, financial controls and the synthetic acceptance plan. + + Map Coverage, Benefits, Claims, remittance, controls and acceptance evidence. - - Inspect authority boundaries, executable evidence and research limitations. + + Follow the operational path from discovery and Booking through covered Care. + + + Review identity, purpose, Consent, scopes, data boundaries and audit behavior. + + + Review authority mappings, controlled exchange and synthetic pilot gates. + + + Inspect reproducible evidence, prior-art boundaries and research limitations. @@ -40,8 +49,8 @@ https://api.heyrafiki.space/v1 Status codes and the error envelope. - - Practitioners, Bookings, Benefits, Sessions, Claims, remittance and Webhooks. + + Map all 31 released operations before opening the endpoint reference. Test records, failure cases and the request runner. diff --git a/insurance/acceptance-testing.mdx b/insurance/acceptance-testing.mdx index a55a1b2..cbeb5db 100644 --- a/insurance/acceptance-testing.mdx +++ b/insurance/acceptance-testing.mdx @@ -13,19 +13,19 @@ Use one isolated Sandbox project and synthetic records for the full payer pilot. ## Pilot control room - + Own the contract commit, environment mapping, retry policy, idempotency keys, Webhook consumer and integration logs. - + Own independent amount recomputation, Benefit interpretation, valuation assumptions, remittance allocation and settlement variance review. - + Own service-code mapping, Practitioner workflow, delivered-service evidence and escalation when operational evidence is incomplete. - + Own scopes, tenant isolation, synthetic-data controls, secret handling, signature verification and data-minimization review. - + Own policy references, decision authority, audit retrieval, incident contacts, activation approval and rollback authority. diff --git a/insurance/claim-valuation-timeline.mdx b/insurance/claim-valuation-timeline.mdx index abe1f8a..d7d31a1 100644 --- a/insurance/claim-valuation-timeline.mdx +++ b/insurance/claim-valuation-timeline.mdx @@ -54,16 +54,16 @@ outstanding = payer_liability - observed_settlement Remittance remains payer advice. Settlement remains independent evidence of money movement. The timeline does not mark a Claim settled from an advice file alone. - + Reconstruct reported Claim development by service, report, decision and settlement dates. Preserve zero-Claim exposure and define the cohort, valuation basis and treatment of reopened or reversed Claims before calculating a portfolio measure. - + Reconcile payer liability to advice, observed movement, ledger evidence and the remaining outstanding amount without netting unrelated balances. - + Trace the Claim from effective policy version through coded decision, communication event, remittance and settlement observation. Each transition retains its source authority and recorded time. - + Validate gapless event sequence, unique event identifiers, nondecreasing knowledge time, integer amounts and balanced adjudication in CI. diff --git a/quickstart.mdx b/quickstart.mdx index 510ce86..1c93060 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,6 +1,7 @@ --- title: "Quickstart" description: "Make the first authenticated request to the Heyrafiki sandbox." +keywords: ["Heyrafiki quickstart", "Sandbox API", "mental healthcare API tutorial"] --- ## 1. Create a sandbox key @@ -71,3 +72,20 @@ curl https://api.heyrafiki.space/v1/bookings \ Sandbox requests use fictitious records. Do not send names, contacts, clinical content or payment credentials in test requests. + +## Continue the integration + + + + Exercise authorization, idempotency, rate limits and recovery before adding a workflow. + + + Check eligibility and complete the pre-authorization sequence. + + + Register an endpoint, verify signatures and handle duplicate deliveries. + + + Browse the 31 released operations by resource area. + + diff --git a/rate-limits.mdx b/rate-limits.mdx index 90300ec..6765eea 100644 --- a/rate-limits.mdx +++ b/rate-limits.mdx @@ -1,6 +1,7 @@ --- title: "Rate limits" description: "Read limits from every response and retry predictably." +keywords: ["API rate limits", "retry backoff", "HTTP 429"] --- Limits are assigned per key and project. Do not hard-code a plan-wide number. diff --git a/requests.mdx b/requests.mdx index 8c8c5bc..003fbec 100644 --- a/requests.mdx +++ b/requests.mdx @@ -1,6 +1,7 @@ --- title: "Requests" description: "Headers, identifiers, timestamps and money." +keywords: ["API request format", "idempotency key", "request ID"] --- Send and receive JSON over HTTPS. diff --git a/research/evidence.mdx b/research/evidence.mdx index 6766c9d..a2a4321 100644 --- a/research/evidence.mdx +++ b/research/evidence.mdx @@ -58,13 +58,13 @@ npm test The public suites support claims about contract coverage, deterministic scoring, bitemporal replay, Consent-aware access boundaries, audit completeness and rejection of declared adversarial mutations. -They do not establish: +Separate clinical and population studies are required for: - clinical validity or diagnostic performance; - effectiveness for a Kenyan or other real population; - actuarial savings or health outcomes; - safety under every production condition; -- novelty, patentability or scientific priority. +- scientific priority or patentability. Those conclusions require a separate protocol, appropriate approvals, licensed instruments, representative data, baseline methods, uncertainty estimates and expert review. @@ -72,7 +72,26 @@ Those conclusions require a separate protocol, appropriate approvals, licensed i A research candidate is ready for formal evaluation only when its problem, assumptions, prior art, baseline, protocol, measures, data rights, failure implications and review owner are written down before outcome claims are made. -The [Assurance Graph](/institutions/assurance-graph) provides the traceability layer. It connects public operations and controls to executable evidence. It is an architecture and conformance artifact, not evidence that the architecture is scientifically novel. +The [Assurance Graph](/institutions/assurance-graph) provides the traceability layer. It connects public operations and controls to executable evidence. Scientific priority is evaluated separately through the comparative protocol and independent review. + +### Candidate under comparative review + +The current candidate tests a two-cutoff, Consent-conditional assurance-path query with fail-closed completeness. The protocol is in Stage 1 independent review. Results follow protocol freeze, comparative evaluation and independent reproduction. + + + + Review the formal query, five baselines, fixed measures and stopping rules. + + + Inspect the article structure before any result is collected. + + + See the closest standards, papers and patent families found by the author search. + + + Follow the independent review, freeze and reproduction gates. + + ## Reporting a mismatch diff --git a/resources.mdx b/resources.mdx index 08f7484..6ab249b 100644 --- a/resources.mdx +++ b/resources.mdx @@ -1,8 +1,29 @@ --- -title: "Resources" -description: "The sandbox resources in the Heyrafiki API." +title: "API overview" +sidebarTitle: "Overview" +description: "Map the released Heyrafiki API across Care, Benefits, Claims, remittance and Webhooks." +keywords: ["Heyrafiki API", "mental healthcare API", "insurance API", "OpenAPI"] --- +The released OpenAPI 1.0.0 contract contains 31 operations across eight resource areas. Every operation in this map is implemented in the Sandbox and generated into an endpoint page under **API reference**. + +## Released surface + +| Area | Operations | What you can do | +| --- | ---: | --- | +| API discovery | 1 | Inspect the authenticated project, environment and API version | +| Practitioners | 3 | List and retrieve synthetic Practitioners and recurring availability | +| Bookings | 3 | List, create and retrieve Bookings | +| Sessions | 2 | List and retrieve minimum-necessary Session records | +| Benefits | 7 | Record Coverage, check eligibility and manage pre-authorization decisions | +| Claims | 7 | Submit, retrieve, query, evidence, adjudicate and reconstruct Claim valuation | +| Remittances | 3 | List, create and retrieve remittance advice and reconciliation state | +| Webhooks | 5 | List, register, retrieve, disable and test endpoints | + +The reference is generated from the same versioned contract used by the public conformance suite. A new endpoint appears here only after implementation, authorization and error behavior, examples, compatibility ownership and sensitive-data review pass the publication gate. + +## Start with one workflow + Discover a synthetic Practitioner, create a Booking, check Benefits and move covered Care from Claim to remittance. ## List Practitioners diff --git a/sandbox.mdx b/sandbox.mdx index 3edc912..851c19b 100644 --- a/sandbox.mdx +++ b/sandbox.mdx @@ -1,6 +1,7 @@ --- title: "Sandbox" description: "Build complete integrations without real Care data." +keywords: ["healthcare API Sandbox", "synthetic data", "integration testing"] --- Use the sandbox for end-to-end development with synthetic data. diff --git a/scopes.mdx b/scopes.mdx index e3c9737..9da0af1 100644 --- a/scopes.mdx +++ b/scopes.mdx @@ -1,6 +1,7 @@ --- title: "Scopes" description: "Grant each key only the capabilities its integration needs." +keywords: ["API scopes", "least privilege", "access control"] --- Scopes are attached to a key when it is issued. diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index 3669ca5..a8ffc84 100644 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -48,15 +48,53 @@ for (const path of publicFiles) { const specPath = join(root, "openapi", "heyrafiki.openapi.yaml"); const spec = readFileSync(specPath, "utf8"); const operations = new Set(); +const operationDetails = []; let currentPath = ""; +let currentOperation = null; +function finishOperation() { + if (!currentOperation) return; + operationDetails.push(currentOperation); + currentOperation = null; +} for (const line of spec.split(/\r?\n/)) { const pathMatch = line.match(/^ (\/[^:]*):\s*$/); if (pathMatch) { + finishOperation(); currentPath = pathMatch[1]; continue; } const methodMatch = line.match(/^ (get|post|put|patch|delete):\s*$/); - if (currentPath && methodMatch) operations.add(`${methodMatch[1].toUpperCase()} ${currentPath}`); + if (currentPath && methodMatch) { + finishOperation(); + const name = `${methodMatch[1].toUpperCase()} ${currentPath}`; + operations.add(name); + currentOperation = { name, body: "" }; + continue; + } + if (currentOperation) currentOperation.body += `${line}\n`; +} +finishOperation(); + +const operationIds = new Set(); +for (const operation of operationDetails) { + const id = operation.body.match(/^ operationId:\s*(\S+)\s*$/m)?.[1]; + if (!id) failures.push(`OpenAPI: ${operation.name} has no operationId`); + else if (operationIds.has(id)) failures.push(`OpenAPI: duplicate operationId ${id}`); + else operationIds.add(id); + if (!/^ summary:\s*\S/m.test(operation.body)) { + failures.push(`OpenAPI: ${operation.name} has no summary`); + } + if (!/^ description:\s*\S/m.test(operation.body)) { + failures.push(`OpenAPI: ${operation.name} has no description`); + } + if (!/^ "2\d\d":/m.test(operation.body)) { + failures.push(`OpenAPI: ${operation.name} has no success response`); + } + for (const status of ["401", "429"]) { + if (!new RegExp(`^ "${status}":`, "m").test(operation.body)) { + failures.push(`OpenAPI: ${operation.name} has no ${status} response`); + } + } } function collectNavigationPages(node) { @@ -78,6 +116,9 @@ function collectNavigationPages(node) { } const activePages = [...new Set(collectNavigationPages(config.navigation))]; +const documentedOperations = new Set( + activePages.filter((page) => /^(GET|POST|PUT|PATCH|DELETE) \//.test(page)), +); for (const page of activePages) { if (/^(GET|POST|PUT|PATCH|DELETE) \//.test(page)) { if (!operations.has(page)) failures.push(`docs.json: unknown OpenAPI operation ${page}`); @@ -85,6 +126,24 @@ for (const page of activePages) { } if (!existsSync(join(root, `${page}.mdx`))) failures.push(`docs.json: missing page ${page}`); } +for (const operation of operations) { + if (!documentedOperations.has(operation)) { + failures.push(`docs.json: undocumented OpenAPI operation ${operation}`); + } +} + +for (const page of activePages.filter( + (entry) => !/^(GET|POST|PUT|PATCH|DELETE) \//.test(entry), +)) { + const label = `${page}.mdx`; + const content = readFileSync(join(root, label), "utf8"); + const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? ""; + for (const field of ["title", "description", "keywords"]) { + if (!new RegExp(`^${field}:\\s*\\S`, "m").test(frontmatter)) { + failures.push(`${label}: missing ${field} frontmatter`); + } + } +} const activeContent = activePages .filter((page) => !/^(GET|POST|PUT|PATCH|DELETE) \//.test(page)) diff --git a/sdks.mdx b/sdks.mdx index 6308f18..223a2fe 100644 --- a/sdks.mdx +++ b/sdks.mdx @@ -8,10 +8,9 @@ Every SDK follows the same OpenAPI contract, authentication rules, idempotency requirements, error envelope and request identifiers. - The current SDK and CLI release is source-only. Registry packages and - versioned GitHub Releases have not been published. Use the reviewed public - repositories and the build commands below until a release appears in the - owning repository. + Install the current SDKs and CLI from the reviewed source repositories using + the build commands below. Registry releases will be linked here after each + clean consumer installation passes. ## Choose a client diff --git a/security/data-boundaries.mdx b/security/data-boundaries.mdx index b6fd252..f1c3118 100644 --- a/security/data-boundaries.mdx +++ b/security/data-boundaries.mdx @@ -1,6 +1,7 @@ --- title: "Data boundaries" description: "How integrations stay useful without exposing more data than they need." +keywords: ["health data boundaries", "data minimization", "healthcare privacy"] --- Heyrafiki applies least privilege to every resource and environment. diff --git a/security/overview.mdx b/security/overview.mdx index 551e217..a85588a 100644 --- a/security/overview.mdx +++ b/security/overview.mdx @@ -1,6 +1,7 @@ --- title: "Security and privacy" description: "What Heyrafiki protects, how access is decided, and what never leaves." +keywords: ["healthcare API security", "Consent", "purpose-based access control"] --- Access is decided by three things together: the role of the person asking, the purpose of the request, and the Consent attached to the record. Any one of them failing denies the request. diff --git a/style.css b/style.css index 344029f..538d3a4 100644 --- a/style.css +++ b/style.css @@ -3,12 +3,13 @@ :root { --hr-brand: #184a34; + --hr-brand-soft: color-mix(in srgb, var(--hr-brand) 34%, transparent); } /* Page title */ #content-area h1, article h1 { - font-size: 1.68rem; + font-size: 1.78rem; line-height: 1.15; letter-spacing: -0.03em; font-weight: 600; @@ -17,7 +18,7 @@ article h1 { /* Section headings */ #content-area h2, article h2 { - font-size: 1.08rem; + font-size: 1.14rem; line-height: 1.25; letter-spacing: -0.02em; font-weight: 600; @@ -26,7 +27,7 @@ article h2 { #content-area h3, article h3 { - font-size: 0.92rem; + font-size: 0.98rem; line-height: 1.3; letter-spacing: -0.015em; font-weight: 600; @@ -37,19 +38,19 @@ article h3 { #content-area li, article p, article li { - font-size: 0.84rem; - line-height: 1.66; + font-size: 0.93rem; + line-height: 1.7; } /* The lede under a page title */ #content-area > div:first-child p:first-of-type { - font-size: 0.9rem; + font-size: 0.98rem; } /* Tables read as data, not prose */ #content-area table, article table { - font-size: 0.8rem; + font-size: 0.84rem; } #content-area th, @@ -61,19 +62,19 @@ article th { /* Code sits a touch smaller so snippets fit without wrapping */ #content-area code, article code { - font-size: 0.78rem; + font-size: 0.82rem; } #content-area pre code, article pre code { - font-size: 0.76rem; + font-size: 0.8rem; line-height: 1.6; } /* Cards on the landing page */ #content-area .card h2, #content-area .card h3 { - font-size: 0.86rem; + font-size: 0.91rem; margin-top: 0; } @@ -90,3 +91,40 @@ article a, article button { text-underline-offset: 0.18em; } + +/* Long role selectors stay compact on desktop and retain deliberate, + discoverable horizontal scrolling when a narrow viewport needs it. */ +#content-area [role="tablist"], +article [role="tablist"] { + gap: 0.2rem; + scrollbar-color: var(--hr-brand-soft) transparent; + scrollbar-width: thin; +} + +#content-area [role="tablist"]::-webkit-scrollbar, +article [role="tablist"]::-webkit-scrollbar { + height: 0.25rem; +} + +#content-area [role="tablist"]::-webkit-scrollbar-track, +article [role="tablist"]::-webkit-scrollbar-track { + background: transparent; +} + +#content-area [role="tablist"]::-webkit-scrollbar-thumb, +article [role="tablist"]::-webkit-scrollbar-thumb { + background: var(--hr-brand-soft); + border-radius: 999px; +} + +#content-area [role="tablist"] button, +article [role="tablist"] button { + font-size: 0.78rem; + white-space: nowrap; +} + +#content-area [role="tablist"] button:focus-visible, +article [role="tablist"] button:focus-visible { + outline: 2px solid color-mix(in srgb, var(--hr-brand) 72%, white); + outline-offset: 2px; +} diff --git a/testing.mdx b/testing.mdx index 376cd81..ce2aaeb 100644 --- a/testing.mdx +++ b/testing.mdx @@ -1,6 +1,7 @@ --- title: "Testing" description: "Build integrations against deterministic sandbox data." +keywords: ["API testing", "Sandbox fixtures", "integration conformance"] --- Use sandbox keys for development, CI and acceptance tests. Sandbox responses contain synthetic data and use the same identifiers, scopes, errors and rate-limit headers as the API contract. diff --git a/versioning.mdx b/versioning.mdx index b5ff503..6643867 100644 --- a/versioning.mdx +++ b/versioning.mdx @@ -1,6 +1,7 @@ --- title: "Versioning" description: "How the Heyrafiki API changes." +keywords: ["API versioning", "breaking changes", "deprecation policy"] --- The version is in the path. diff --git a/webhooks.mdx b/webhooks.mdx index 4b2fd9e..da76f9a 100644 --- a/webhooks.mdx +++ b/webhooks.mdx @@ -1,6 +1,7 @@ --- title: "Webhooks" description: "Register an endpoint, verify signatures and test delivery." +keywords: ["Webhooks", "Webhook signatures", "event delivery"] --- ## Register an endpoint