babelfhir-ts 1.0.35 → 1.0.37

package/README.md

@@ -23,9 +23,30 @@
 - **Install any FHIR profile as a node module**—use `babelfhir-ts install` to add Implementation Guides directly to your project
 
 <!-- PARITY-BADGES:START - Do not remove or modify this section -->
-## Pipeline Parity Results
+## Continuous Validation
 
-BabelFHIR-TS validators achieve **100% parity** with the Firely .NET SDK validator across major Implementation Guides:
+Every pull request runs two independent CI pipelines that validate generated code against real-world FHIR Implementation Guides. For each IG, the pipeline:
+
+1. Downloads the FHIR package from a registry
+2. Generates TypeScript interfaces, validators, and classes
+3. Compiles the output with `tsc` (zero errors required)
+4. Generates `empty()` and `random()` test resources for every profile
+5. Validates those resources against two external FHIR validators
+
+### Tested Implementation Guides
+
+| Implementation Guide | Package | Profiles |
+|---|---|---|
+| US Core | `hl7.fhir.us.core@8.0.0` | Patient, Condition, Observation, Encounter, … |
+| ISiK Basis (Germany) | `de.gematik.isik-basismodul@4.0.3` | ISiKPatient, ISiKDiagnose, … |
+| IPS (International Patient Summary) | `hl7.fhir.uv.ips@2.0.0` | Composition, MedicationStatement, … |
+| SMART App Launch | `hl7.fhir.uv.smart-app-launch@2.2.0` | WellKnown endpoints |
+| CH Core (Switzerland) | `ch.fhir.ig.ch-core@5.0.0` | CHCorePatient, CHCoreEncounter, … |
+| DaVinci PAS | `hl7.fhir.us.davinci-pas@2.0.1` | PASClaim, PASClaimResponse, … |
+
+### Validation with Firely .NET SDK
+
+The first pipeline validates generated resources using the [Firely .NET SDK validator](https://docs.fire.ly/projects/Firely-NET-SDK/) (v3.0.1). Results are published as live badges:
 
 ![US Core 8.0.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-us-core.json)
 ![ISiK Basis 4.0.3](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-isik-basis.json)
@@ -33,14 +54,11 @@ BabelFHIR-TS validators achieve **100% parity** with the Firely .NET SDK validat
 ![SMART 2.2.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-smart.json)
 ![CH Core 5.0.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-ch-core.json)
 
-> **11 profiles excluded** due to [Firely SDK bugs](./docs/FIRELY-VALIDATOR-BUGS.md) — validated successfully with HL7 Java Validator.
-
-📊 **[Full Report](https://gist.github.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f)** · *Last updated: Dec 10, 2025*
+> 11 profiles are excluded from this pipeline due to schema loading issues in the Firely SDK. These profiles validate successfully with the HL7 Java Validator below. Details in [docs/FIRELY-VALIDATOR-BUGS.md](./docs/FIRELY-VALIDATOR-BUGS.md).
 
-<!-- HL7-PARITY-BADGES:START - Do not remove or modify this section -->
-### HL7 Java Validator Parity
+### Validation with HL7 Java Validator
 
-Generated `random()` and `empty()` methods also pass structural validation with the [official HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator):
+The second pipeline validates using the [official HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator) (v6.3.11), the reference implementation for FHIR conformance checking:
 
 ![US Core 8.0.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-hl7-us-core.json)
 ![ISiK Basis 4.0.3](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-hl7-isik-basis.json)
@@ -48,9 +66,9 @@ Generated `random()` and `empty()` methods also pass structural validation with
 ![SMART 2.2.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-hl7-smart.json)
 ![CH Core 5.0.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-hl7-ch-core.json)
 
-> **Note:** Terminology validation (codes bound to ValueSets) requires a terminology server. The HL7 validator validates terminology bindings against `tx.fhir.org` by default, which may report errors for generated placeholder codes. Use `--tx-server https://tx.fhir.org/r4` during generation to expand ValueSets and use real codes.
+> Terminology validation requires a tx server. The pipeline uses `--tx-server https://tx.fhir.org/r4` during generation to expand ValueSets and produce valid codes.
 
-📊 **[Full Report](https://gist.github.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f)** · *Last updated: Jan 24, 2026*
+📊 **[Full Report & Badge Data](https://gist.github.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f)**
 <!-- HL7-PARITY-BADGES:END -->
 <!-- PARITY-BADGES:END -->
 
@@ -233,7 +251,7 @@ For comprehensive conformance testing, use the official [HL7 FHIR Validator](htt
   - Reference integrity constraints
 
   Use `random()` for development, testing, and prototyping, but always validate production data on the FHIR server side.
-- **`validate()` parity**: The generated validation methods execute FHIRPath expressions and check constraints from StructureDefinitions, but are **only guaranteed to match** the Firely .NET SDK validator for scenarios covered by our test suite (see GitHub actions). Edge cases, complex slicing patterns, or profiles not in our test pipeline may produce different results. For production conformance testing, use the official [HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator) as the source of truth.
+- **`validate()` coverage**: The generated validation methods execute FHIRPath expressions and check constraints from StructureDefinitions. They are tested against the HL7 Java Validator and the Firely .NET SDK for the Implementation Guides listed in the [Continuous Validation](#continuous-validation) section. Edge cases, complex slicing patterns, or profiles not in the CI pipeline may produce different results. For production conformance testing, use the official [HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator) as the source of truth.
 
 ### FHIR Version Support
 
@@ -242,7 +260,7 @@ For comprehensive conformance testing, use the official [HL7 FHIR Validator](htt
 
 ### Reporting Issues
 
-If you encounter an Implementation Guide that doesn't generate correctly, please [open an issue](https://github.com/quotentiroler/BabelFHIR-ts/issues) with:
+If you encounter an Implementation Guide that doesn't generate correctly, please [open an issue](https://github.com/Max-Health-Inc/BabelFHIR-TS/issues) with:
 
 - The package name and version
 - The specific StructureDefinition URL
@@ -266,6 +284,6 @@ For security issues, please see [SECURITY.md](SECURITY.md) for our security poli
 ## Links
 
 - [npm package](https://www.npmjs.com/package/babelfhir-ts)
-- [GitHub repository](https://github.com/quotentiroler/BabelFHIR-ts)
-- [Issue tracker](https://github.com/quotentiroler/BabelFHIR-ts/issues)
+- [GitHub repository](https://github.com/Max-Health-Inc/BabelFHIR-TS)
+- [Issue tracker](https://github.com/Max-Health-Inc/BabelFHIR-TS/issues)
 - [Changelog](CHANGELOG.md)

package/out/src/generator/clientGenerator.js

@@ -28,9 +28,11 @@ export function generateClient(options) {
     generateResourceWriter(clientDir, resourceTypes);
     generateBundleParser(clientDir, resourceTypes);
     generateFhirClient(clientDir, resourceTypes);
+    generateSmartAuth(clientDir);
+    generateSmartClient(clientDir, resourceTypes);
     generateIndex(clientDir, resourceTypes);
     generateReadme(clientDir);
-    log.success(`Generated FHIR client with ${resourceTypes.length} resource types`);
+    log.success(`Generated FHIR client with ${resourceTypes.length} resource types + SMART auth`);
 }
 /**
  * Generate types.ts
@@ -120,18 +122,28 @@ export interface FhirResourceSearcher<T> {
  */
 ${readerTypes}
 
+/**
+ * Custom fetch function type for injecting auth headers
+ */
+export type FetchFn = typeof globalThis.fetch;
+
 /**
  * Implementation of FHIR resource reader
  */
 export class FhirResourceReader<T> implements FhirResourceSearcher<T> {
+  private readonly fetchFn: FetchFn;
+
   constructor(
     public readonly baseUrl: string,
     public readonly resourceType: string,
-  ) {}
+    fetchFn?: FetchFn,
+  ) {
+    this.fetchFn = fetchFn ?? globalThis.fetch.bind(globalThis);
+  }
 
   async read(id: string): Promise<WithId<T>> {
     const url = \`\${this.baseUrl}/\${this.resourceType}/\${id}\`;
-    const response = await fetch(url, {
+    const response = await this.fetchFn(url, {
       headers: {
         Accept: "application/fhir+json",
       },
@@ -163,7 +175,7 @@ export class FhirResourceReader<T> implements FhirResourceSearcher<T> {
       }
     }
 
-    const response = await fetch(url.toString(), {
+    const response = await this.fetchFn(url.toString(), {
       headers: {
         Accept: "application/fhir+json",
       },
@@ -197,7 +209,7 @@ export class FhirResourceReader<T> implements FhirResourceSearcher<T> {
 
       if (!nextLink) break;
 
-      const response = await fetch(nextLink, {
+      const response = await this.fetchFn(nextLink, {
         headers: {
           Accept: "application/fhir+json",
         },
@@ -258,18 +270,25 @@ export interface FhirResourceWriter<T> {
  */
 ${writerTypes}
 
+import type { FetchFn } from "./resource-reader.js";
+
 /**
  * Implementation of FHIR resource writer
  */
 export class FhirResourceWriterImpl<T> implements FhirResourceWriter<T> {
+  private readonly fetchFn: FetchFn;
+
   constructor(
     public readonly baseUrl: string,
     public readonly resourceType: string,
-  ) {}
+    fetchFn?: FetchFn,
+  ) {
+    this.fetchFn = fetchFn ?? globalThis.fetch.bind(globalThis);
+  }
 
   async create(resource: T): Promise<WithId<T>> {
     const url = \`\${this.baseUrl}/\${this.resourceType}\`;
-    const response = await fetch(url, {
+    const response = await this.fetchFn(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/fhir+json",
@@ -289,7 +308,7 @@ export class FhirResourceWriterImpl<T> implements FhirResourceWriter<T> {
 
   async update(resource: WithId<T>): Promise<WithId<T>> {
     const url = \`\${this.baseUrl}/\${this.resourceType}/\${resource.id}\`;
-    const response = await fetch(url, {
+    const response = await this.fetchFn(url, {
       method: "PUT",
       headers: {
         "Content-Type": "application/fhir+json",
@@ -309,7 +328,7 @@ export class FhirResourceWriterImpl<T> implements FhirResourceWriter<T> {
 
   async delete(id: string): Promise<void> {
     const url = \`\${this.baseUrl}/\${this.resourceType}/\${id}\`;
-    const response = await fetch(url, {
+    const response = await this.fetchFn(url, {
       method: "DELETE",
     });
 
@@ -516,7 +535,7 @@ function generateFhirClient(clientDir, resourceTypes) {
         .map((rt) => {
         const methodName = rt.profileName.charAt(0).toLowerCase() + rt.profileName.slice(1);
         return `  ${methodName}(): ${rt.profileName}Reader {
-    return new FhirResourceReader(this.baseUrl, "${rt.baseResourceType}");
+    return new FhirResourceReader(this.baseUrl, "${rt.baseResourceType}", this.fetchFn);
   }`;
     })
         .join("\n\n");
@@ -524,13 +543,14 @@ function generateFhirClient(clientDir, resourceTypes) {
         .map((rt) => {
         const methodName = rt.profileName.charAt(0).toLowerCase() + rt.profileName.slice(1);
         return `  ${methodName}(): ${rt.profileName}Writer {
-    return new FhirResourceWriterImpl(this.baseUrl, "${rt.baseResourceType}");
+    return new FhirResourceWriterImpl(this.baseUrl, "${rt.baseResourceType}", this.fetchFn);
   }`;
     })
         .join("\n\n");
     const content = `import {
 ${readerImports}
   FhirResourceReader,
+  type FetchFn,
 } from "./resource-reader.js";
 import {
 ${writerImports}
@@ -541,7 +561,10 @@ ${writerImports}
  * FHIR Client for reading resources
  */
 export class FhirReadClient {
-  constructor(private readonly baseUrl: string) {}
+  constructor(
+    private readonly baseUrl: string,
+    private readonly fetchFn?: FetchFn,
+  ) {}
 
 ${readerMethods}
 }
@@ -550,21 +573,34 @@ ${readerMethods}
  * FHIR Client for writing resources
  */
 export class FhirWriteClient {
-  constructor(private readonly baseUrl: string) {}
+  constructor(
+    private readonly baseUrl: string,
+    private readonly fetchFn?: FetchFn,
+  ) {}
 
 ${writerMethods}
 }
 
 /**
- * Main FHIR Client
+ * Main FHIR Client — works with plain fetch or an authenticated fetch wrapper.
+ *
+ * @example
+ * // Unauthenticated
+ * const client = new FhirClient("https://fhir.example.com");
+ *
+ * // With custom fetch (e.g. from SmartFhirClient)
+ * const client = new FhirClient("https://fhir.example.com", authenticatedFetch);
  */
 export class FhirClient {
   private readonly readClient: FhirReadClient;
   private readonly writeClient: FhirWriteClient;
 
-  constructor(public readonly baseUrl: string) {
-    this.readClient = new FhirReadClient(baseUrl);
-    this.writeClient = new FhirWriteClient(baseUrl);
+  constructor(
+    public readonly baseUrl: string,
+    fetchFn?: FetchFn,
+  ) {
+    this.readClient = new FhirReadClient(baseUrl, fetchFn);
+    this.writeClient = new FhirWriteClient(baseUrl, fetchFn);
   }
 
   /**
@@ -584,6 +620,604 @@ export class FhirClient {
 `;
     fs.writeFileSync(path.join(clientDir, "fhir-client.ts"), content);
 }
+/**
+ * Generate smart-auth.ts — PKCE, discovery, token management (static, IG-agnostic)
+ */
+function generateSmartAuth(clientDir) {
+    const content = `/**
+ * SMART on FHIR Authorization Module
+ *
+ * Implements SMART App Launch Framework (v2) with PKCE.
+ * Works in any browser environment — no framework dependencies.
+ *
+ * @see https://hl7.org/fhir/smart-app-launch/
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface SmartConfig {
+  /** OAuth2 client_id registered with the auth server */
+  clientId: string;
+  /** Redirect URI registered with the auth server */
+  redirectUri: string;
+  /** FHIR server base URL (used as \`aud\` param) */
+  fhirBaseUrl: string;
+  /** Space-separated OAuth2 scopes */
+  scopes: string;
+  /** Optional storage backend (defaults to sessionStorage) */
+  storage?: Storage;
+  /** Optional prefix for storage keys (defaults to "smart_") */
+  storagePrefix?: string;
+  /** Where to redirect after IdP logout (defaults to current origin) */
+  postLogoutRedirectUri?: string;
+}
+
+export interface SmartToken {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  scope: string;
+  id_token?: string;
+  refresh_token?: string;
+  /** Extracted from id_token or token response */
+  fhirUser?: string;
+  /** Patient context from EHR launch */
+  patient?: string;
+  /** Encounter context from EHR launch */
+  encounter?: string;
+}
+
+export interface SmartConfiguration {
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint?: string;
+  introspection_endpoint?: string;
+  revocation_endpoint?: string;
+  end_session_endpoint?: string;
+  capabilities?: string[];
+}
+
+export type LaunchMode = "standalone" | "ehr";
+
+// ── PKCE helpers ─────────────────────────────────────────────────────────────
+
+function generateRandomString(length: number): string {
+  const array = new Uint8Array(length);
+  crypto.getRandomValues(array);
+  return Array.from(array, (b) => b.toString(36).padStart(2, "0"))
+    .join("")
+    .slice(0, length);
+}
+
+async function sha256(plain: string): Promise<ArrayBuffer> {
+  const encoder = new TextEncoder();
+  return crypto.subtle.digest("SHA-256", encoder.encode(plain));
+}
+
+function base64UrlEncode(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\\+/g, "-").replace(/\\//g, "_").replace(/=+$/, "");
+}
+
+// ── Storage keys ─────────────────────────────────────────────────────────────
+
+function storageKeys(prefix: string) {
+  return {
+    token: \`\${prefix}token\`,
+    verifier: \`\${prefix}code_verifier\`,
+    state: \`\${prefix}state\`,
+    expiresAt: \`\${prefix}expires_at\`,
+    launchMode: \`\${prefix}launch_mode\`,
+  } as const;
+}
+
+// ── Discovery ────────────────────────────────────────────────────────────────
+
+/**
+ * Discover SMART authorization endpoints from a FHIR server.
+ * Tries \`.well-known/smart-configuration\` first, falls back to CapabilityStatement.
+ */
+export async function discoverEndpoints(fhirBaseUrl: string): Promise<SmartConfiguration> {
+  const smartUrl = \`\${fhirBaseUrl}/.well-known/smart-configuration\`;
+  try {
+    const res = await fetch(smartUrl);
+    if (res.ok) return (await res.json()) as SmartConfiguration;
+  } catch {
+    // fallthrough to CapabilityStatement
+  }
+
+  const metaUrl = \`\${fhirBaseUrl}/metadata\`;
+  const res = await fetch(metaUrl, {
+    headers: { Accept: "application/fhir+json" },
+  });
+  if (!res.ok) {
+    throw new Error(\`Failed to discover SMART endpoints from \${metaUrl}\`);
+  }
+
+  const meta = await res.json();
+  const security = meta.rest?.[0]?.security;
+  const oauthExt = security?.extension?.find(
+    (e: { url: string }) =>
+      e.url === "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris",
+  );
+  const findExt = (url: string): string | undefined =>
+    oauthExt?.extension?.find((e: { url: string }) => e.url === url)?.valueUri;
+
+  const authorization_endpoint = findExt("authorize");
+  const token_endpoint = findExt("token");
+  if (!authorization_endpoint || !token_endpoint) {
+    throw new Error(
+      "Could not find SMART authorization/token endpoints in CapabilityStatement",
+    );
+  }
+  return { authorization_endpoint, token_endpoint };
+}
+
+// ── SmartAuth class ──────────────────────────────────────────────────────────
+
+/**
+ * Manages the SMART on FHIR authorization lifecycle.
+ *
+ * @example
+ * const auth = new SmartAuth({
+ *   clientId: "my-app",
+ *   redirectUri: "http://localhost:3000/callback",
+ *   fhirBaseUrl: "https://fhir.example.com/fhir",
+ *   scopes: "openid fhirUser patient/*.read",
+ * });
+ *
+ * // Check if this is a callback
+ * if (auth.isCallback()) {
+ *   const token = await auth.handleCallback();
+ * } else {
+ *   await auth.authorize(); // redirects to auth server
+ * }
+ *
+ * // Create authenticated fetch
+ * const authFetch = auth.createAuthenticatedFetch();
+ */
+export class SmartAuth {
+  private readonly storage: Storage;
+  private readonly keys: ReturnType<typeof storageKeys>;
+
+  constructor(public readonly config: SmartConfig) {
+    this.storage = config.storage ?? sessionStorage;
+    this.keys = storageKeys(config.storagePrefix ?? "smart_");
+  }
+
+  // ── Launch ───────────────────────────────────────────────────────────
+
+  /** Detect launch mode from current URL parameters */
+  detectLaunchMode(): LaunchMode {
+    const params = new URLSearchParams(window.location.search);
+    return params.has("launch") && params.has("iss") ? "ehr" : "standalone";
+  }
+
+  /** Start standalone SMART launch (redirects the browser) */
+  async authorize(): Promise<void> {
+    const mode = this.detectLaunchMode();
+    if (mode === "ehr") {
+      const params = new URLSearchParams(window.location.search);
+      await this.startEhrLaunch(
+        params.get("launch")!,
+        params.get("iss")!,
+      );
+    } else {
+      await this.startStandaloneLaunch();
+    }
+  }
+
+  /** Start standalone SMART launch */
+  async startStandaloneLaunch(): Promise<void> {
+    const endpoints = await discoverEndpoints(this.config.fhirBaseUrl);
+    const { codeChallenge, codeVerifier, state } = await this.preparePkce();
+
+    this.storage.setItem(this.keys.launchMode, "standalone");
+
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      scope: this.config.scopes,
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+      aud: this.config.fhirBaseUrl,
+    });
+
+    window.location.href = \`\${endpoints.authorization_endpoint}?\${params}\`;
+  }
+
+  /** Start EHR SMART launch */
+  async startEhrLaunch(launch: string, iss: string): Promise<void> {
+    const endpoints = await discoverEndpoints(this.config.fhirBaseUrl);
+    const { codeChallenge, codeVerifier, state } = await this.preparePkce();
+
+    this.storage.setItem(this.keys.launchMode, "ehr");
+
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      scope: this.config.scopes,
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+      aud: iss,
+      launch,
+    });
+
+    window.location.href = \`\${endpoints.authorization_endpoint}?\${params}\`;
+  }
+
+  // ── Callback ─────────────────────────────────────────────────────────
+
+  /** Check if the current URL is an OAuth callback */
+  isCallback(): boolean {
+    const params = new URLSearchParams(window.location.search);
+    return params.has("code") || params.has("error");
+  }
+
+  /** Handle the OAuth callback — exchanges code for token */
+  async handleCallback(): Promise<SmartToken> {
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    const state = params.get("state");
+    const error = params.get("error");
+
+    if (error) {
+      throw new Error(
+        \`Authorization error: \${error} — \${params.get("error_description") ?? ""}\`,
+      );
+    }
+    if (!code) {
+      throw new Error("Missing authorization code in callback");
+    }
+
+    const savedState = this.storage.getItem(this.keys.state);
+    if (state !== savedState) {
+      throw new Error("State mismatch — possible CSRF");
+    }
+
+    const codeVerifier = this.storage.getItem(this.keys.verifier);
+    if (!codeVerifier) {
+      throw new Error("Missing PKCE code_verifier");
+    }
+
+    const endpoints = await discoverEndpoints(this.config.fhirBaseUrl);
+
+    const body = new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: this.config.redirectUri,
+      client_id: this.config.clientId,
+      code_verifier: codeVerifier,
+    });
+
+    const res = await fetch(endpoints.token_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(\`Token exchange failed (\${res.status}): \${text}\`);
+    }
+
+    const token: SmartToken = await res.json();
+
+    // Extract fhirUser from id_token claims
+    if (token.id_token) {
+      try {
+        const payload = JSON.parse(atob(token.id_token.split(".")[1]));
+        token.fhirUser = payload.fhirUser ?? payload.profile;
+      } catch {
+        // id_token decode failed — non-critical
+      }
+    }
+
+    // Clean up PKCE state
+    this.storage.removeItem(this.keys.verifier);
+    this.storage.removeItem(this.keys.state);
+
+    // Save token + expiry
+    this.storage.setItem(this.keys.token, JSON.stringify(token));
+    if (token.expires_in) {
+      const expiresAt = Date.now() + (token.expires_in - 60) * 1000;
+      this.storage.setItem(this.keys.expiresAt, String(expiresAt));
+    }
+
+    return token;
+  }
+
+  // ── Token management ─────────────────────────────────────────────────
+
+  /** Get the stored token, or null if not authenticated */
+  getToken(): SmartToken | null {
+    const raw = this.storage.getItem(this.keys.token);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as SmartToken;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Get the stored launch mode */
+  getLaunchMode(): LaunchMode {
+    return (this.storage.getItem(this.keys.launchMode) as LaunchMode) ?? "standalone";
+  }
+
+  /** Check if the user is authenticated */
+  isAuthenticated(): boolean {
+    return this.getToken() !== null;
+  }
+
+  /** Check if the current token is expired */
+  isTokenExpired(): boolean {
+    const expiresAt = this.storage.getItem(this.keys.expiresAt);
+    if (!expiresAt) return false;
+    return Date.now() >= Number(expiresAt);
+  }
+
+  /** Clear stored token and auth state */
+  clearToken(): void {
+    this.storage.removeItem(this.keys.token);
+    this.storage.removeItem(this.keys.expiresAt);
+    this.storage.removeItem(this.keys.launchMode);
+  }
+
+  /**
+   * Full logout — clears local state and redirects to the IdP's
+   * end_session_endpoint so the Keycloak / OAuth2 session is terminated.
+   *
+   * Falls back to just clearing local state if no end_session_endpoint
+   * is advertised by the server.
+   */
+  async logout(postLogoutRedirectUri?: string): Promise<void> {
+    const token = this.getToken();
+    this.clearToken();
+
+    try {
+      const endpoints = await discoverEndpoints(this.config.fhirBaseUrl);
+      if (endpoints.end_session_endpoint) {
+        const params = new URLSearchParams({
+          post_logout_redirect_uri:
+            postLogoutRedirectUri ??
+            this.config.postLogoutRedirectUri ??
+            window.location.origin,
+          client_id: this.config.clientId,
+        });
+        if (token?.id_token) {
+          params.set("id_token_hint", token.id_token);
+        }
+        window.location.href = \`\${endpoints.end_session_endpoint}?\${params}\`;
+        return;
+      }
+    } catch {
+      // discovery failed — fall through to local-only logout
+    }
+
+    // No end_session_endpoint — just reload to the app root
+    window.location.href = postLogoutRedirectUri ?? this.config.postLogoutRedirectUri ?? window.location.origin;
+  }
+
+  /** Refresh the access token using the refresh_token grant */
+  async refreshAccessToken(): Promise<SmartToken | null> {
+    const token = this.getToken();
+    if (!token?.refresh_token) return null;
+
+    try {
+      const endpoints = await discoverEndpoints(this.config.fhirBaseUrl);
+      const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: token.refresh_token,
+        client_id: this.config.clientId,
+      });
+
+      const res = await fetch(endpoints.token_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+      });
+
+      if (!res.ok) return null;
+
+      const newToken: SmartToken = await res.json();
+
+      // Preserve context from previous token if not in the new one
+      if (!newToken.fhirUser && token.fhirUser) newToken.fhirUser = token.fhirUser;
+      if (!newToken.refresh_token && token.refresh_token)
+        newToken.refresh_token = token.refresh_token;
+      if (!newToken.patient && token.patient) newToken.patient = token.patient;
+      if (!newToken.encounter && token.encounter) newToken.encounter = token.encounter;
+
+      this.storage.setItem(this.keys.token, JSON.stringify(newToken));
+      if (newToken.expires_in) {
+        const expiresAt = Date.now() + (newToken.expires_in - 60) * 1000;
+        this.storage.setItem(this.keys.expiresAt, String(expiresAt));
+      }
+      return newToken;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Get a valid (non-expired) token, refreshing if needed */
+  async getValidToken(): Promise<SmartToken | null> {
+    const token = this.getToken();
+    if (!token) return null;
+    if (!this.isTokenExpired()) return token;
+    return this.refreshAccessToken();
+  }
+
+  // ── Authenticated fetch ──────────────────────────────────────────────
+
+  /**
+   * Create a fetch wrapper that injects the Bearer token.
+   * Automatically refreshes expired tokens when a refresh_token is available.
+   *
+   * Pass the returned function to \`FhirClient\` as the \`fetchFn\` parameter.
+   *
+   * @example
+   * const auth = new SmartAuth(config);
+   * const client = new FhirClient(config.fhirBaseUrl, auth.createAuthenticatedFetch());
+   */
+  createAuthenticatedFetch(): typeof globalThis.fetch {
+    const self = this;
+
+    return async function authenticatedFetch(
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ): Promise<Response> {
+      const token = await self.getValidToken();
+      if (!token) {
+        throw new Error("No valid SMART token available — authorize first");
+      }
+
+      const headers = new Headers(init?.headers);
+      headers.set("Authorization", \`Bearer \${token.access_token}\`);
+
+      const response = await fetch(input, { ...init, headers });
+
+      // Auto-retry once on 401 with a refreshed token
+      if (response.status === 401 && token.refresh_token) {
+        const refreshed = await self.refreshAccessToken();
+        if (refreshed) {
+          headers.set("Authorization", \`Bearer \${refreshed.access_token}\`);
+          return fetch(input, { ...init, headers });
+        }
+      }
+
+      return response;
+    };
+  }
+
+  // ── Internal ─────────────────────────────────────────────────────────
+
+  private async preparePkce(): Promise<{
+    codeVerifier: string;
+    codeChallenge: string;
+    state: string;
+  }> {
+    const codeVerifier = generateRandomString(64);
+    const codeChallenge = base64UrlEncode(await sha256(codeVerifier));
+    const state = generateRandomString(32);
+
+    this.storage.setItem(this.keys.verifier, codeVerifier);
+    this.storage.setItem(this.keys.state, state);
+
+    return { codeVerifier, codeChallenge, state };
+  }
+}
+`;
+    fs.writeFileSync(path.join(clientDir, "smart-auth.ts"), content);
+}
+/**
+ * Generate smart-client.ts — SmartFhirClient that wraps FhirClient with SMART auth
+ */
+function generateSmartClient(clientDir, resourceTypes) {
+    const content = `import { FhirClient, FhirReadClient, FhirWriteClient } from "./fhir-client.js";
+import { SmartAuth } from "./smart-auth.js";
+import type { SmartConfig, SmartToken, LaunchMode } from "./smart-auth.js";
+
+export type { SmartConfig, SmartToken, LaunchMode };
+
+/**
+ * SMART on FHIR enabled FHIR Client.
+ *
+ * Combines \`SmartAuth\` (PKCE, discovery, token management) with the typed
+ * \`FhirClient\` so every request is automatically authenticated.
+ *
+ * @example
+ * const smart = new SmartFhirClient({
+ *   clientId: "my-app",
+ *   redirectUri: "http://localhost:3000/callback",
+ *   fhirBaseUrl: "https://fhir.example.com/fhir",
+ *   scopes: "openid fhirUser patient/*.read",
+ * });
+ *
+ * // On page load — either handle callback or start auth
+ * if (smart.isCallback()) {
+ *   await smart.handleCallback();
+ * } else if (!smart.isAuthenticated()) {
+ *   await smart.authorize(); // redirects
+ *   return;
+ * }
+ *
+ * // Use the typed FHIR client — auth headers injected automatically
+ * const patient = await smart.client.read().patient().read("123");
+ */
+export class SmartFhirClient {
+  /** The underlying SMART auth manager */
+  public readonly auth: SmartAuth;
+
+  /** The typed FHIR client with automatic auth headers */
+  public readonly client: FhirClient;
+
+  constructor(config: SmartConfig) {
+    this.auth = new SmartAuth(config);
+    this.client = new FhirClient(
+      config.fhirBaseUrl,
+      this.auth.createAuthenticatedFetch(),
+    );
+  }
+
+  // ── Convenience delegates ────────────────────────────────────────────
+
+  /** Start the authorization flow (auto-detects standalone vs EHR launch) */
+  async authorize(): Promise<void> {
+    return this.auth.authorize();
+  }
+
+  /** Check if the current page is an OAuth callback */
+  isCallback(): boolean {
+    return this.auth.isCallback();
+  }
+
+  /** Handle the OAuth callback and store the token */
+  async handleCallback(): Promise<SmartToken> {
+    return this.auth.handleCallback();
+  }
+
+  /** Check if the user has a stored token */
+  isAuthenticated(): boolean {
+    return this.auth.isAuthenticated();
+  }
+
+  /** Get the current token (null if not authenticated) */
+  getToken(): SmartToken | null {
+    return this.auth.getToken();
+  }
+
+  /** Get the launch mode (standalone or ehr) */
+  getLaunchMode(): LaunchMode {
+    return this.auth.getLaunchMode();
+  }
+
+  /** Full logout — clears local state and ends the IdP session */
+  async logout(postLogoutRedirectUri?: string): Promise<void> {
+    return this.auth.logout(postLogoutRedirectUri);
+  }
+
+  // ── Typed read/write access ──────────────────────────────────────────
+
+  /** Get the read client (all requests are authenticated) */
+  read(): FhirReadClient {
+    return this.client.read();
+  }
+
+  /** Get the write client (all requests are authenticated) */
+  write(): FhirWriteClient {
+    return this.client.write();
+  }
+}
+`;
+    fs.writeFileSync(path.join(clientDir, "smart-client.ts"), content);
+}
 /**
  * Generate index.ts
  */
@@ -596,6 +1230,7 @@ function generateIndex(clientDir, resourceTypes) {
         .join("\n");
     const content = `export { FhirClient, FhirReadClient, FhirWriteClient } from "./fhir-client.js";
 export { FhirResourceReader } from "./resource-reader.js";
+export type { FetchFn } from "./resource-reader.js";
 export type {
 ${readerTypes}
   FhirResourceSearcher,
@@ -608,6 +1243,9 @@ ${writerTypes}
 export { BundleParser, parseBundle } from "./bundle-parser.js";
 export type { BundleEntry } from "./bundle-parser.js";
 export type { Bundle, FhirResource, SearchParams, WithId } from "./types.js";
+export { SmartAuth, discoverEndpoints } from "./smart-auth.js";
+export type { SmartConfig, SmartToken, SmartConfiguration, LaunchMode } from "./smart-auth.js";
+export { SmartFhirClient } from "./smart-client.js";
 `;
     fs.writeFileSync(path.join(clientDir, "index.ts"), content);
 }
@@ -617,7 +1255,7 @@ export type { Bundle, FhirResource, SearchParams, WithId } from "./types.js";
 function generateReadme(clientDir) {
     const content = `# FHIR Client
 
-Auto-generated type-safe FHIR client for TypeScript.
+Auto-generated type-safe FHIR client for TypeScript with SMART on FHIR authorization.
 
 ## Usage
 
@@ -658,6 +1296,85 @@ const updated = await client.write().patient().update({
 await client.write().patient().delete('patient-id');
 \`\`\`
 
+### SMART on FHIR Authorization
+
+The client includes full SMART App Launch Framework (v2) support with PKCE.
+
+#### Quick Start — SmartFhirClient
+
+\`\`\`typescript
+import { SmartFhirClient } from './fhir-client';
+
+const smart = new SmartFhirClient({
+  clientId: 'my-app',
+  redirectUri: 'http://localhost:3000/callback',
+  fhirBaseUrl: 'https://fhir.example.com/fhir',
+  scopes: 'openid fhirUser patient/*.read',
+});
+
+// On page load — handle callback or start auth
+if (smart.isCallback()) {
+  await smart.handleCallback();
+} else if (!smart.isAuthenticated()) {
+  await smart.authorize(); // redirects to auth server
+  return;
+}
+
+// All requests include the Bearer token automatically
+const patient = await smart.read().patient().read('123');
+const token = smart.getToken(); // access SmartToken
+\`\`\`
+
+#### Advanced — SmartAuth + FhirClient
+
+For more control, use \`SmartAuth\` directly with \`FhirClient\`:
+
+\`\`\`typescript
+import { SmartAuth, FhirClient } from './fhir-client';
+
+const auth = new SmartAuth({
+  clientId: 'my-app',
+  redirectUri: 'http://localhost:3000/callback',
+  fhirBaseUrl: 'https://fhir.example.com/fhir',
+  scopes: 'openid fhirUser patient/*.read launch/patient',
+});
+
+// Get an authenticated fetch function
+const authFetch = auth.createAuthenticatedFetch();
+
+// Pass it to FhirClient
+const client = new FhirClient('https://fhir.example.com/fhir', authFetch);
+\`\`\`
+
+#### EHR Launch
+
+EHR launches are auto-detected from URL parameters (\`launch\` + \`iss\`):
+
+\`\`\`typescript
+const smart = new SmartFhirClient({ ... });
+
+// authorize() auto-detects and handles both modes
+await smart.authorize();
+
+// After callback
+const mode = smart.getLaunchMode(); // "standalone" | "ehr"
+const token = smart.getToken();
+console.log('Patient context:', token?.patient);
+console.log('Encounter context:', token?.encounter);
+\`\`\`
+
+#### Token Management
+
+\`\`\`typescript
+// Check authentication state
+smart.isAuthenticated(); // boolean
+smart.getToken();        // SmartToken | null
+smart.getLaunchMode();   // "standalone" | "ehr"
+
+// Logout
+smart.logout();
+\`\`\`
+
 ### Bundle Parsing
 
 \`\`\`typescript
@@ -700,6 +1417,23 @@ for (const entry of entries) {
   console.log(\`Search score: \${entry.search?.score}\`);
 }
 \`\`\`
+
+### Custom Fetch
+
+You can pass any custom fetch function to \`FhirClient\` — useful for logging, retries, or custom auth:
+
+\`\`\`typescript
+import { FhirClient } from './fhir-client';
+
+const loggingFetch: typeof fetch = async (input, init) => {
+  console.log('Request:', input);
+  const response = await fetch(input, init);
+  console.log('Response:', response.status);
+  return response;
+};
+
+const client = new FhirClient('https://fhir.example.com/fhir', loggingFetch);
+\`\`\`
 `;
     fs.writeFileSync(path.join(clientDir, "README.md"), content);
 }

package/out/src/generator/index.js

@@ -158,14 +158,13 @@ async function generateIndexFile(dir) {
     const files = fs.readdirSync(dir, { withFileTypes: true });
     const exports = [];
     const exportedNames = new Set();
-    // First pass: collect all files and their exports
+    // First pass: collect all files and their exported names
     const fileExports = new Map();
     for (const file of files) {
         if (file.isFile() && file.name.endsWith('.ts') && !file.name.endsWith('.d.ts') && file.name !== 'index.ts' && file.name !== 'RandomSupport.ts') {
             const filePath = path.join(dir, file.name);
             const content = fs.readFileSync(filePath, 'utf-8');
             const names = new Set();
-            // Extract export names (interfaces, classes, functions, types)
             const exportMatches = content.matchAll(/export\s+(?:interface|class|type|const|function)\s+(\w+)/g);
             for (const match of exportMatches) {
                 names.add(match[1]);
@@ -173,26 +172,35 @@ async function generateIndexFile(dir) {
             fileExports.set(file.name, names);
         }
     }
-    // Second pass: only export from files that have unique exports or are primary files
+    // Second pass: export files, using selective named exports when there are conflicts
     for (const file of files) {
         if (file.isFile() && file.name.endsWith('.ts') && !file.name.endsWith('.d.ts') && file.name !== 'index.ts' && file.name !== 'RandomSupport.ts') {
             const baseName = file.name.replace('.ts', '');
             const fileNames = fileExports.get(file.name) || new Set();
-            // Check if this file's exports would conflict with already exported names
-            let hasConflict = false;
+            // Find which names from this file conflict with already-exported names
+            const conflicting = new Set();
+            const unique = new Set();
             for (const name of fileNames) {
                 if (exportedNames.has(name)) {
-                    hasConflict = true;
-                    break;
+                    conflicting.add(name);
+                }
+                else {
+                    unique.add(name);
                 }
             }
-            // Only export if no conflicts, or if it's a Class file (which are primary)
-            if (!hasConflict || file.name.endsWith('Class.ts')) {
+            if (conflicting.size === 0) {
+                // No conflicts — use simple wildcard export
                 exports.push(`export * from './${baseName}.js';`);
-                // Mark all names from this file as exported
-                for (const name of fileNames) {
-                    exportedNames.add(name);
-                }
+            }
+            else if (unique.size > 0) {
+                // Has conflicts but also has unique names — use selective named export
+                const names = [...unique].sort().join(', ');
+                exports.push(`export { ${names} } from './${baseName}.js';`);
+            }
+            // If all names conflict (unique.size === 0), skip entirely
+            // Track all names from this file as exported
+            for (const name of fileNames) {
+                exportedNames.add(name);
             }
         }
     }
@@ -1280,7 +1288,7 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
             license: 'MIT',
             // fhirpath is required at runtime by validators; keep as peer so host decides version
             peerDependencies: {
-                'fhirpath': '^4.0.0'
+                'fhirpath': '^3.0.0 || ^4.0.0'
             },
             // Type definitions for FHIR are needed for the .d.ts files
             dependencies: {
@@ -1291,10 +1299,14 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         fs.writeFileSync(generatedPackageJsonPath, JSON.stringify(generatedPackageJson, null, 2));
         logger.log(`Created package.json in generated folder: ${packageName}-generated@${packageVersion}`);
         // Copy fhir-r4.d.ts ambient module declaration to support fhir/r4 imports
-        // The file is at out/fhir-r4.d.ts (root of compiled output)
-        const fhirR4DtsSource = path.join(path.dirname(path.dirname(fileURLToPath(import.meta.url))), 'fhir-r4.d.ts');
+        // In dev: src/generator/ -> src/fhir-r4.d.ts. In compiled: out/src/generator/ -> out/fhir-r4.d.ts
+        const _selfDir = path.dirname(fileURLToPath(import.meta.url));
+        const fhirR4DtsSource = [
+            path.join(_selfDir, '..', 'fhir-r4.d.ts'),
+            path.join(_selfDir, '..', '..', 'fhir-r4.d.ts'),
+        ].find(p => fs.existsSync(p));
         const fhirR4DtsDest = path.join(outputDir, 'fhir-r4.d.ts');
-        if (fs.existsSync(fhirR4DtsSource)) {
+        if (fhirR4DtsSource) {
             fs.copyFileSync(fhirR4DtsSource, fhirR4DtsDest);
             logger.log('Copied fhir-r4.d.ts ambient module declaration');
         }

package/out/src/main.js

@@ -5,11 +5,25 @@ import { getCacheConfig, getFhirPackagesCacheDir, clearAllCaches, ensureCacheDir
 import { fetchArrayBuffer } from "./generator/fetchUtils.js";
 import fs from 'fs';
 import path from 'path';
-import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 import { logger } from './logger.js';
-const require = createRequire(import.meta.url);
-const packageJson = require('../package.json');
+// Resolve package.json relative to this file — works from both src/ (dev) and out/src/ (compiled)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const _pkgJsonPath = [
+    path.resolve(__dirname, '../package.json'),
+    path.resolve(__dirname, '../../package.json'),
+].find(p => {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8')).name === 'babelfhir-ts';
+    }
+    catch {
+        return false;
+    }
+});
+if (!_pkgJsonPath)
+    throw new Error('Cannot find babelfhir-ts package.json');
+const packageJson = JSON.parse(fs.readFileSync(_pkgJsonPath, 'utf8'));
 function printUsage() {
     console.log("BabelFHIR-TS: Generate TypeScript interfaces from FHIR StructureDefinitions");
     console.log("");
@@ -80,11 +94,27 @@ function cleanupCache() {
         console.log('Cache cleaned.');
     }
 }
+/** Detect the package manager used in the current working directory */
+function detectPackageManager() {
+    const cwd = process.cwd();
+    const isWin = process.platform === 'win32';
+    if (fs.existsSync(path.join(cwd, 'bun.lock')) || fs.existsSync(path.join(cwd, 'bun.lockb'))) {
+        return { cmd: isWin ? 'bun.exe' : 'bun', args: ['add'] };
+    }
+    if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) {
+        return { cmd: isWin ? 'pnpm.cmd' : 'pnpm', args: ['add'] };
+    }
+    if (fs.existsSync(path.join(cwd, 'yarn.lock'))) {
+        return { cmd: isWin ? 'yarn.cmd' : 'yarn', args: ['add'] };
+    }
+    return { cmd: isWin ? 'npm.cmd' : 'npm', args: ['install'] };
+}
 function npmInstall(packagePath) {
     return new Promise((resolve, reject) => {
-        console.log(`Installing package with npm...`);
-        const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-        const child = spawn(npmCmd, ['install', packagePath], {
+        const pm = detectPackageManager();
+        const pmName = path.basename(pm.cmd).replace(/\.(cmd|exe)$/, '');
+        console.log(`Installing package with ${pmName}...`);
+        const child = spawn(pm.cmd, [...pm.args, packagePath], {
             stdio: 'inherit',
             shell: true
         });
@@ -94,11 +124,11 @@ function npmInstall(packagePath) {
                 resolve();
             }
             else {
-                reject(new Error(`npm install failed with exit code ${code}`));
+                reject(new Error(`${pmName} install failed with exit code ${code}`));
             }
         });
         child.on('error', (err) => {
-            reject(new Error(`Failed to run npm install: ${err.message}`));
+            reject(new Error(`Failed to run ${pmName} install: ${err.message}`));
         });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babelfhir-ts",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "BabelFHIR-TS: generate TypeScript interfaces, validators, and helper classes from FHIR R4 StructureDefinitions (profiles) directly inside package archives.",
   "type": "module",
   "main": "out/src/main.js",