@backwork/x278

x278

TypeScript SDK and reference implementation for x278, Backwork's proposed agent-native protocol for prior authorization.

x278 models prior authorization as a typed exchange between provider-side and payer-side software agents. A provider agent submits a structured request. A payer agent returns an actionable determination: approved, denied, info-needed, or pended. The provider agent can then attach evidence, wait for review, correct the request, or appeal without restarting the authorization context.

This package is a protocol SDK and runnable reference environment. It is not a certified payer integration, a substitute for Da Vinci PAS conformance testing, or legal/compliance advice.

Install

npm install @backwork/x278

bun add @backwork/x278

The package ships dual ESM/CJS builds, declaration maps, and subpath exports for SDK, HTTP transport, FHIR/PAS helpers, signing, conformance, and protocol types.

Quick Start

Run the provider loop against the deterministic in-memory payer:

import {
  createMockX278Client,
  kneeReplacementMissingDocs
} from "@backwork/x278";

const client = createMockX278Client({
  collectEvidence: (_request, requirements) =>
    requirements.map((requirement) => ({
      id: requirement.id,
      value: `chart evidence for ${requirement.id}`,
      source: "chart"
    }))
});

const trace = await client.requestWithTrace(kneeReplacementMissingDocs);

console.log(trace.steps.map((step) => step.status));
// ["info-needed", "approved"]

console.log(trace.final.authNumber);

The same client loop also handles pended determinations by awaiting the returned subscription handle, and denied determinations by returning a coded reason plus appeal path.

HTTP Client

Use @backwork/x278/http when calling an x278-compatible payer endpoint:

import { createX278HttpClient } from "@backwork/x278/http";

const client = createX278HttpClient({
  baseUrl: "https://payer.example/x278",
  bearerToken: process.env.X278_BEARER_TOKEN,
  collectEvidence: async (_request, requirements) =>
    requirements.map((requirement) => ({
      id: requirement.id,
      value: "supporting chart evidence",
      source: "chart"
    }))
});

const capabilities = await client.capabilities();
const determination = await client.request({
  patient: { memberId: "A1234567", dob: "1971-03-02" },
  provider: { npi: "1972648392", tin: "84-1234567" },
  service: {
    code: "27447",
    codeSystem: "CPT",
    diagnosis: ["M17.11"],
    placeOfService: "21",
    requestedStart: "2026-06-01",
    units: 1,
    urgency: "standard"
  },
  supportingInfo: []
});

The HTTP client includes production-oriented defaults:

• 30 second request timeout
• retry support for transient HTTP failures
• Retry-After handling
• bearer token and custom header hooks
• request, response, retry, and error lifecycle hooks
• redacted debug logging
• typed ProtocolError failures with request IDs where available
• /.well-known/x278 capabilities discovery

For local parity, createX278HttpClientFromEnv() reads X278_PAYER_URL and X278_BEARER_TOKEN.

Protocol States

State	Meaning	Next action
approved	Authorization approved by rules or reviewer	Use the returned authorization number and validity window
denied	Request denied with coded reason and appeal path	Correct, resubmit, or appeal
info-needed	Payer needs specific documentation	Attach evidence and resume the same authId
pended	Request accepted but not final	Await the returned subscription/update handle
error	Malformed or unprocessable exchange	Fix the request or contact the payer

Public Exports

Import	Purpose
@backwork/x278	Full public SDK surface
@backwork/x278/http	Fetch-backed HTTP client and transport
@backwork/x278/sdk	Promise and Effect provider clients
@backwork/x278/conformance	Conformance harness for x278 transports
@backwork/x278/types	Protocol schemas, domain types, and typed errors
@backwork/x278/schemas	Schema-focused alias for protocol validation
@backwork/x278/evidence	DTR-style evidence and QuestionnaireResponse helpers
@backwork/x278/fhir-pas	FHIR/PAS/DTR mapping helpers
@backwork/x278/policy	Versioned executable policy adapter interface
@backwork/x278/signing	Canonical hashing and signed receipt utilities
@backwork/x278/smart	SMART Backend Services token provider utilities
@backwork/x278/subscriptions	Local subscription/webhook broker helpers
@backwork/x278/payer-agent	Reference payer agent service
@backwork/x278/provider-client	Lower-level provider loop primitives

Effect and Promise APIs

x278 is implemented with Effect schemas and services internally, while exposing a Promise API for conventional TypeScript applications.

• Use createX278EffectClient and runX278ConformanceEffect inside Effect applications.
• Use createX278Client, createX278HttpClient, and runX278Conformance in Promise-based services.
• API boundaries accept unknown where appropriate and validate into typed protocol objects before transport use.

Conformance

Transport implementers can run the conformance harness against any x278 transport:

import { createMockPayer, runX278Conformance } from "@backwork/x278";

const report = await runX278Conformance(createMockPayer());

if (!report.ok) {
  throw new Error("x278 conformance failed");
}

The harness exercises the core behaviors described by the protocol: approval, denial, information-needed retry, pended review, signature verification, audit records, and bounded workflow handling.

Conformance reports can also be serialized for release artifacts:

import {
  runX278Conformance,
  toConformanceBadge,
  toConformanceMarkdown
} from "@backwork/x278";

const report = await runX278Conformance(transport);

console.log(toConformanceMarkdown(report));
console.log(toConformanceBadge(report));

Examples

The repository includes runnable examples that use the same public package exports consumers install from npm:

Command	What it shows
bun run example:mock	Full provider loop against the in-memory payer, including info-needed, pended, and denied paths
bun run example:conformance	Running the conformance harness against a transport
bun run payer:http + bun run example:http	HTTP client usage against the local reference payer

For the HTTP example, start the payer in one terminal:

bun run payer:http

Then run the client from another terminal:

bun run example:http

Local Development

bun install
bun run typecheck
bun run test
bun run build

Useful verification commands:

Command	Purpose
bun run test	Unit and protocol behavior tests
bun run test:live	Live OpenAI Agents SDK and Anthropic SDK proof tests
bun run release:smoke	Packaged ESM/CJS consumer smoke test
bun run release:attw	Package export/type validation
bun run docker:realistic	Provider and payer containers over HTTP
bun run docker:fhir	HTTP scenario with HAPI FHIR validation
bun run prove:full	Full local release proof gate

Live agent tests require provider API keys in the environment. The normal test suite does not call paid model APIs.

Specification

• Core x278 specification
• HTTP transport
• FHIR/PAS adapter expectations

x278 is designed to interoperate with FHIR prior authorization infrastructure, including Da Vinci PAS, DTR, and CRD patterns, rather than replace those rails. Where X12 278/275 applies, production implementers still need the appropriate mapping, licensing, and trading-partner testing outside this SDK.

Status and Boundaries

The repository currently includes:

• protocol schemas and typed determination states
• Promise and Effect SDK clients
• production HTTP client and transport
• deterministic reference payer agent
• signed terminal determinations and audit records
• FHIR/PAS mapping helpers
• conformance and release proof harnesses
• Docker-based realistic scenarios

Before production healthcare use, organizations still need real payer endpoint registration, SMART Backend Services/OAuth configuration, PAS/FHIR conformance testing, HIPAA/security review, operational monitoring, and policy/legal review.

This project is not affiliated with CMS, HL7, X12, or the Da Vinci Project.

License

MIT. See LICENSE.