{"id":50951200,"url":"https://github.com/backworkai/x278","last_synced_at":"2026-06-18T01:32:16.827Z","repository":{"id":361035477,"uuid":"1252759600","full_name":"backworkai/x278","owner":"backworkai","description":"Agent-native prior authorization protocol reference implementation and TypeScript SDK.","archived":false,"fork":false,"pushed_at":"2026-05-29T00:12:10.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T00:21:37.144Z","etag":null,"topics":["agents","bun","effect-ts","fhir","healthcare","prior-authorization","typescript","x278"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/backworkai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T20:58:42.000Z","updated_at":"2026-05-29T00:12:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/backworkai/x278","commit_stats":null,"previous_names":["backworkai/x278"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/backworkai/x278","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backworkai%2Fx278","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backworkai%2Fx278/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backworkai%2Fx278/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backworkai%2Fx278/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/backworkai","download_url":"https://codeload.github.com/backworkai/x278/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backworkai%2Fx278/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34472822,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","bun","effect-ts","fhir","healthcare","prior-authorization","typescript","x278"],"created_at":"2026-06-18T01:32:16.029Z","updated_at":"2026-06-18T01:32:16.813Z","avatar_url":"https://github.com/backworkai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# x278\n\n[![npm](https://img.shields.io/npm/v/@backwork/x278.svg)](https://www.npmjs.com/package/@backwork/x278)\n[![CI](https://github.com/backworkai/x278/actions/workflows/ci.yml/badge.svg)](https://github.com/backworkai/x278/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-2D2824.svg)](LICENSE)\n[![Runtime: Bun](https://img.shields.io/badge/runtime-Bun-C65D3D.svg)](https://bun.sh)\n[![Effect TS](https://img.shields.io/badge/Effect-3.x-2F8F83.svg)](https://effect.website)\n\nTypeScript SDK and reference implementation for x278, Backwork's proposed\nagent-native protocol for prior authorization.\n\nx278 models prior authorization as a typed exchange between provider-side and\npayer-side software agents. A provider agent submits a structured request. A\npayer agent returns an actionable determination: `approved`, `denied`,\n`info-needed`, or `pended`. The provider agent can then attach evidence, wait for\nreview, correct the request, or appeal without restarting the authorization\ncontext.\n\nThis package is a protocol SDK and runnable reference environment. It is not a\ncertified payer integration, a substitute for Da Vinci PAS conformance testing,\nor legal/compliance advice.\n\n## Install\n\n```bash\nnpm install @backwork/x278\n```\n\n```bash\nbun add @backwork/x278\n```\n\nThe package ships dual ESM/CJS builds, declaration maps, and subpath exports for\nSDK, HTTP transport, FHIR/PAS helpers, signing, conformance, and protocol types.\n\n## Quick Start\n\nRun the provider loop against the deterministic in-memory payer:\n\n```ts\nimport {\n  createMockX278Client,\n  kneeReplacementMissingDocs\n} from \"@backwork/x278\";\n\nconst client = createMockX278Client({\n  collectEvidence: (_request, requirements) =\u003e\n    requirements.map((requirement) =\u003e ({\n      id: requirement.id,\n      value: `chart evidence for ${requirement.id}`,\n      source: \"chart\"\n    }))\n});\n\nconst trace = await client.requestWithTrace(kneeReplacementMissingDocs);\n\nconsole.log(trace.steps.map((step) =\u003e step.status));\n// [\"info-needed\", \"approved\"]\n\nconsole.log(trace.final.authNumber);\n```\n\nThe same client loop also handles `pended` determinations by awaiting the\nreturned subscription handle, and `denied` determinations by returning a coded\nreason plus appeal path.\n\n## HTTP Client\n\nUse `@backwork/x278/http` when calling an x278-compatible payer endpoint:\n\n```ts\nimport { createX278HttpClient } from \"@backwork/x278/http\";\n\nconst client = createX278HttpClient({\n  baseUrl: \"https://payer.example/x278\",\n  bearerToken: process.env.X278_BEARER_TOKEN,\n  collectEvidence: async (_request, requirements) =\u003e\n    requirements.map((requirement) =\u003e ({\n      id: requirement.id,\n      value: \"supporting chart evidence\",\n      source: \"chart\"\n    }))\n});\n\nconst capabilities = await client.capabilities();\nconst determination = await client.request({\n  patient: { memberId: \"A1234567\", dob: \"1971-03-02\" },\n  provider: { npi: \"1972648392\", tin: \"84-1234567\" },\n  service: {\n    code: \"27447\",\n    codeSystem: \"CPT\",\n    diagnosis: [\"M17.11\"],\n    placeOfService: \"21\",\n    requestedStart: \"2026-06-01\",\n    units: 1,\n    urgency: \"standard\"\n  },\n  supportingInfo: []\n});\n```\n\nThe HTTP client includes production-oriented defaults:\n\n- 30 second request timeout\n- retry support for transient HTTP failures\n- `Retry-After` handling\n- bearer token and custom header hooks\n- request, response, retry, and error lifecycle hooks\n- redacted debug logging\n- typed `ProtocolError` failures with request IDs where available\n- `/.well-known/x278` capabilities discovery\n\nFor local parity, `createX278HttpClientFromEnv()` reads `X278_PAYER_URL` and\n`X278_BEARER_TOKEN`.\n\n## Protocol States\n\n| State | Meaning | Next action |\n| --- | --- | --- |\n| `approved` | Authorization approved by rules or reviewer | Use the returned authorization number and validity window |\n| `denied` | Request denied with coded reason and appeal path | Correct, resubmit, or appeal |\n| `info-needed` | Payer needs specific documentation | Attach evidence and resume the same `authId` |\n| `pended` | Request accepted but not final | Await the returned subscription/update handle |\n| `error` | Malformed or unprocessable exchange | Fix the request or contact the payer |\n\n## Public Exports\n\n| Import | Purpose |\n| --- | --- |\n| `@backwork/x278` | Full public SDK surface |\n| `@backwork/x278/http` | Fetch-backed HTTP client and transport |\n| `@backwork/x278/sdk` | Promise and Effect provider clients |\n| `@backwork/x278/conformance` | Conformance harness for x278 transports |\n| `@backwork/x278/types` | Protocol schemas, domain types, and typed errors |\n| `@backwork/x278/schemas` | Schema-focused alias for protocol validation |\n| `@backwork/x278/evidence` | DTR-style evidence and QuestionnaireResponse helpers |\n| `@backwork/x278/fhir-pas` | FHIR/PAS/DTR mapping helpers |\n| `@backwork/x278/policy` | Versioned executable policy adapter interface |\n| `@backwork/x278/signing` | Canonical hashing and signed receipt utilities |\n| `@backwork/x278/smart` | SMART Backend Services token provider utilities |\n| `@backwork/x278/subscriptions` | Local subscription/webhook broker helpers |\n| `@backwork/x278/payer-agent` | Reference payer agent service |\n| `@backwork/x278/provider-client` | Lower-level provider loop primitives |\n\n## Effect and Promise APIs\n\nx278 is implemented with Effect schemas and services internally, while exposing a\nPromise API for conventional TypeScript applications.\n\n- Use `createX278EffectClient` and `runX278ConformanceEffect` inside Effect\n  applications.\n- Use `createX278Client`, `createX278HttpClient`, and `runX278Conformance` in\n  Promise-based services.\n- API boundaries accept `unknown` where appropriate and validate into typed\n  protocol objects before transport use.\n\n## Conformance\n\nTransport implementers can run the conformance harness against any x278 transport:\n\n```ts\nimport { createMockPayer, runX278Conformance } from \"@backwork/x278\";\n\nconst report = await runX278Conformance(createMockPayer());\n\nif (!report.ok) {\n  throw new Error(\"x278 conformance failed\");\n}\n```\n\nThe harness exercises the core behaviors described by the protocol: approval,\ndenial, information-needed retry, pended review, signature verification, audit\nrecords, and bounded workflow handling.\n\nConformance reports can also be serialized for release artifacts:\n\n```ts\nimport {\n  runX278Conformance,\n  toConformanceBadge,\n  toConformanceMarkdown\n} from \"@backwork/x278\";\n\nconst report = await runX278Conformance(transport);\n\nconsole.log(toConformanceMarkdown(report));\nconsole.log(toConformanceBadge(report));\n```\n\n## Examples\n\nThe repository includes runnable examples that use the same public package\nexports consumers install from npm:\n\n| Command | What it shows |\n| --- | --- |\n| `bun run example:mock` | Full provider loop against the in-memory payer, including `info-needed`, `pended`, and `denied` paths |\n| `bun run example:conformance` | Running the conformance harness against a transport |\n| `bun run payer:http` + `bun run example:http` | HTTP client usage against the local reference payer |\n\nFor the HTTP example, start the payer in one terminal:\n\n```bash\nbun run payer:http\n```\n\nThen run the client from another terminal:\n\n```bash\nbun run example:http\n```\n\n## Local Development\n\n```bash\nbun install\nbun run typecheck\nbun run test\nbun run build\n```\n\nUseful verification commands:\n\n| Command | Purpose |\n| --- | --- |\n| `bun run test` | Unit and protocol behavior tests |\n| `bun run test:live` | Live OpenAI Agents SDK and Anthropic SDK proof tests |\n| `bun run release:smoke` | Packaged ESM/CJS consumer smoke test |\n| `bun run release:attw` | Package export/type validation |\n| `bun run docker:realistic` | Provider and payer containers over HTTP |\n| `bun run docker:fhir` | HTTP scenario with HAPI FHIR validation |\n| `bun run prove:full` | Full local release proof gate |\n\nLive agent tests require provider API keys in the environment. The normal test\nsuite does not call paid model APIs.\n\n## Specification\n\n- [Core x278 specification](specs/x278-specification-v0.md)\n- [HTTP transport](specs/transports/http.md)\n- [FHIR/PAS adapter expectations](specs/adapters/fhir-pas.md)\n\nx278 is designed to interoperate with FHIR prior authorization infrastructure,\nincluding Da Vinci PAS, DTR, and CRD patterns, rather than replace those rails.\nWhere X12 278/275 applies, production implementers still need the appropriate\nmapping, licensing, and trading-partner testing outside this SDK.\n\n## Status and Boundaries\n\nThe repository currently includes:\n\n- protocol schemas and typed determination states\n- Promise and Effect SDK clients\n- production HTTP client and transport\n- deterministic reference payer agent\n- signed terminal determinations and audit records\n- FHIR/PAS mapping helpers\n- conformance and release proof harnesses\n- Docker-based realistic scenarios\n\nBefore production healthcare use, organizations still need real payer endpoint\nregistration, SMART Backend Services/OAuth configuration, PAS/FHIR conformance\ntesting, HIPAA/security review, operational monitoring, and policy/legal review.\n\nThis project is not affiliated with CMS, HL7, X12, or the Da Vinci Project.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackworkai%2Fx278","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbackworkai%2Fx278","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackworkai%2Fx278/lists"}