feat: add AsyncFhir2OmopClient and fhir2omop service support

.fern/metadata.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "5.49.1",
+  "cliVersion": "5.50.1",
   "generatorName": "fernapi/fern-java-sdk",
   "generatorVersion": "4.9.2",
   "generatorConfig": {
@@ -10,10 +10,10 @@
     "enable-wire-tests": true,
     "publish-to": "central"
   },
-  "originGitCommit": "64f369254225bd6c2d4c58d87f59165d7e8e8dc9",
+  "originGitCommit": "fff9ecb3e3ee9847a86bfb09de6df7e477ecd13e",
   "originGitCommitIsDirty": true,
   "invokedBy": "ci",
   "requestedVersion": "AUTO",
   "ciProvider": "unknown",
-  "sdkVersion": "17.5.0"
+  "sdkVersion": "17.6.0"
 }

build.gradle

@@ -48,7 +48,7 @@ java {
 
 group = 'com.phenoml.maven'
 
-version = '17.5.0'
+version = '17.6.0'
 
 jar {
     dependsOn(":generatePomFileForMavenPublication")
@@ -79,7 +79,7 @@ publishing {
         maven(MavenPublication) {
             groupId = 'com.phenoml.maven'
             artifactId = 'phenoml-java-sdk'
-            version = '17.5.0'
+            version = '17.6.0'
             from components.java
             pom {
                 name = 'phenoml'

changelog.md

@@ -1,3 +1,12 @@
+## [17.6.0] - 2026-06-18
+### Added
+- **`Fhir2OmopClient` / `AsyncFhir2OmopClient`** — new synchronous and asynchronous clients (plus raw-response variants) accessible via `PhenomlClient.fhir2Omop()` and `AsyncPhenomlClient.fhir2Omop()`, exposing `create(CreateOmopRequest)` to convert a FHIR R4 resource or Bundle to OMOP CDM v5.4 rows via `POST /fhir2omop/create`.
+- **`CreateOmopRequest` / `CreateOmopResponse`** — new request/response types for the FHIR-to-OMOP conversion endpoint, carrying `fhirResources` and returning `tables`, `mappings`, `dropped`, `vocabVersion`, `summary`, `success`, and `message` fields.
+- **OMOP CDM v5.4 row types** — new `PersonRow`, `VisitOccurrenceRow`, `ConditionOccurrenceRow`, `DrugExposureRow`, `ProcedureOccurrenceRow`, `MeasurementRow`, and `ObservationRow` classes aggregated under `OmopTables`.
+- **`MappingEntry` / `Summary` / `DroppedResource`** — new supporting types describing per-coding resolution status (`ALREADY_STANDARD`, `MAPPED`, `UNCHECKED`, `UNMAPPED`), aggregate mapping statistics, and resources that could not be shaped into OMOP rows.
+- **`BadRequestError`, `UnauthorizedError`, `InternalServerError`, `ServiceUnavailableError`** — new typed exception classes extending `PhenomlClientApiException`, thrown for HTTP 400, 401, 500, and 503 responses from the FHIR-to-OMOP endpoint.
+- **`Provider.AIDBOX`** — `"aidbox"` is now a supported value in the `Provider` enum, with a corresponding `Visitor.visitAidbox()` method.
+
 ## [17.5.0] - 2026-06-15
 ### Added
 - **`Provider.AIDBOX`** — `"aidbox"` is now a supported value in the `Provider` enum (with a corresponding `Visitor.visitAidbox()` method).

code-examples.json

@@ -2,8 +2,8 @@
   "metadata": {
     "language": "java",
     "packageName": "com.phenoml.maven:phenoml-java-sdk",
-    "sdkVersion": "17.5.0",
-    "specCommit": "64f369254225bd6c2d4c58d87f59165d7e8e8dc9",
+    "sdkVersion": "17.6.0",
+    "specCommit": "fff9ecb3e3ee9847a86bfb09de6df7e477ecd13e",
     "generatorName": "fernapi/fern-java-sdk"
   },
   "renderRules": {

reference.md

@@ -3036,6 +3036,32 @@ Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows
 (person, visit_occurrence, condition_occurrence, drug_exposure,
 procedure_occurrence, measurement, observation).
 
+Resource support is intentionally limited to the OMOP tables returned by
+this endpoint:
+- `Patient` -> `person`
+- `Encounter` -> `visit_occurrence`
+- `Condition` -> `condition_occurrence`
+- `Procedure` -> `procedure_occurrence`
+- `MedicationRequest`, `MedicationStatement`, and
+  `MedicationAdministration` -> `drug_exposure`
+- `Immunization` -> `drug_exposure`
+- `Observation` with a numeric `valueQuantity`, `valueInteger`, or
+  numeric-looking `valueString` (for example `"<2"`) -> `measurement`
+- non-numeric `Observation` -> `observation`
+- `AllergyIntolerance` -> `observation`
+
+`Medication` is supported only as reference data for medication
+resources; it is not emitted as its own row because OMOP CDM has no
+Medication table. Other reference/admin resources such as `Practitioner`,
+`Organization`, `Location`, `Coverage`, and `Claim`, and clinical
+workflow/document resources such as `DiagnosticReport`, `ServiceRequest`,
+`CarePlan`, `DocumentReference`, `Composition`, `Specimen`, and
+`DeviceUseStatement`, are currently accepted in a Bundle but are not
+shaped into OMOP rows. Unsupported resource types are ignored rather than
+listed under `dropped`; `dropped` is reserved for supported resource types
+that were missing the subject/patient, code, or medication reference data
+needed to produce a valid row.
+
 Each resource's primary clinical coding is resolved to a standard OMOP
 `concept_id`. Alongside the OMOP rows grouped by table (`tables`), the
 response carries `mappings` (how each source coding resolved, linked back
@@ -3151,9 +3177,12 @@ client.fhir2Omop().create(
 **fhirResources:** `Map<String, Object>` 
 
 FHIR resources (single resource or Bundle). Must contain at least one
-Patient resource. Resources are mapped to OMOP rows; standalone
-Medication resources are consumed by medication references rather than
-mapped to their own table.
+Patient resource. Supported row-producing resources are Patient,
+Encounter, Condition, Procedure, MedicationRequest,
+MedicationStatement, MedicationAdministration, Immunization,
+Observation, and AllergyIntolerance. Standalone Medication resources
+are consumed by medication references rather than mapped to their own
+table. Other resource types are accepted but ignored.
 
 </dd>
 </dl>

src/main/java/com/phenoml/api/core/ClientOptions.java

@@ -38,10 +38,10 @@ private ClientOptions(
         this.headers.putAll(headers);
         this.headers.putAll(new HashMap<String, String>() {
             {
-                put("User-Agent", "com.phenoml.maven:phenoml-java-sdk/17.5.0");
+                put("User-Agent", "com.phenoml.maven:phenoml-java-sdk/17.6.0");
                 put("X-Fern-Language", "JAVA");
                 put("X-Fern-SDK-Name", "com.phenoml.fern:api-sdk");
-                put("X-Fern-SDK-Version", "17.5.0");
+                put("X-Fern-SDK-Version", "17.6.0");
             }
         });
         this.headerSuppliers = headerSuppliers;

src/main/java/com/phenoml/api/resources/fhir2omop/AsyncFhir2OmopClient.java

@@ -30,6 +30,32 @@ public AsyncRawFhir2OmopClient withRawResponse() {
      * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows
      * (person, visit_occurrence, condition_occurrence, drug_exposure,
      * procedure_occurrence, measurement, observation).
+     * <p>Resource support is intentionally limited to the OMOP tables returned by
+     * this endpoint:</p>
+     * <ul>
+     * <li><code>Patient</code> -&gt; <code>person</code></li>
+     * <li><code>Encounter</code> -&gt; <code>visit_occurrence</code></li>
+     * <li><code>Condition</code> -&gt; <code>condition_occurrence</code></li>
+     * <li><code>Procedure</code> -&gt; <code>procedure_occurrence</code></li>
+     * <li><code>MedicationRequest</code>, <code>MedicationStatement</code>, and
+     * <code>MedicationAdministration</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Immunization</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Observation</code> with a numeric <code>valueQuantity</code>, <code>valueInteger</code>, or
+     * numeric-looking <code>valueString</code> (for example <code>&quot;&lt;2&quot;</code>) -&gt; <code>measurement</code></li>
+     * <li>non-numeric <code>Observation</code> -&gt; <code>observation</code></li>
+     * <li><code>AllergyIntolerance</code> -&gt; <code>observation</code></li>
+     * </ul>
+     * <p><code>Medication</code> is supported only as reference data for medication
+     * resources; it is not emitted as its own row because OMOP CDM has no
+     * Medication table. Other reference/admin resources such as <code>Practitioner</code>,
+     * <code>Organization</code>, <code>Location</code>, <code>Coverage</code>, and <code>Claim</code>, and clinical
+     * workflow/document resources such as <code>DiagnosticReport</code>, <code>ServiceRequest</code>,
+     * <code>CarePlan</code>, <code>DocumentReference</code>, <code>Composition</code>, <code>Specimen</code>, and
+     * <code>DeviceUseStatement</code>, are currently accepted in a Bundle but are not
+     * shaped into OMOP rows. Unsupported resource types are ignored rather than
+     * listed under <code>dropped</code>; <code>dropped</code> is reserved for supported resource types
+     * that were missing the subject/patient, code, or medication reference data
+     * needed to produce a valid row.</p>
      * <p>Each resource's primary clinical coding is resolved to a standard OMOP
      * <code>concept_id</code>. Alongside the OMOP rows grouped by table (<code>tables</code>), the
      * response carries <code>mappings</code> (how each source coding resolved, linked back
@@ -62,6 +88,32 @@ public CompletableFuture<CreateOmopResponse> create(CreateOmopRequest request) {
      * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows
      * (person, visit_occurrence, condition_occurrence, drug_exposure,
      * procedure_occurrence, measurement, observation).
+     * <p>Resource support is intentionally limited to the OMOP tables returned by
+     * this endpoint:</p>
+     * <ul>
+     * <li><code>Patient</code> -&gt; <code>person</code></li>
+     * <li><code>Encounter</code> -&gt; <code>visit_occurrence</code></li>
+     * <li><code>Condition</code> -&gt; <code>condition_occurrence</code></li>
+     * <li><code>Procedure</code> -&gt; <code>procedure_occurrence</code></li>
+     * <li><code>MedicationRequest</code>, <code>MedicationStatement</code>, and
+     * <code>MedicationAdministration</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Immunization</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Observation</code> with a numeric <code>valueQuantity</code>, <code>valueInteger</code>, or
+     * numeric-looking <code>valueString</code> (for example <code>&quot;&lt;2&quot;</code>) -&gt; <code>measurement</code></li>
+     * <li>non-numeric <code>Observation</code> -&gt; <code>observation</code></li>
+     * <li><code>AllergyIntolerance</code> -&gt; <code>observation</code></li>
+     * </ul>
+     * <p><code>Medication</code> is supported only as reference data for medication
+     * resources; it is not emitted as its own row because OMOP CDM has no
+     * Medication table. Other reference/admin resources such as <code>Practitioner</code>,
+     * <code>Organization</code>, <code>Location</code>, <code>Coverage</code>, and <code>Claim</code>, and clinical
+     * workflow/document resources such as <code>DiagnosticReport</code>, <code>ServiceRequest</code>,
+     * <code>CarePlan</code>, <code>DocumentReference</code>, <code>Composition</code>, <code>Specimen</code>, and
+     * <code>DeviceUseStatement</code>, are currently accepted in a Bundle but are not
+     * shaped into OMOP rows. Unsupported resource types are ignored rather than
+     * listed under <code>dropped</code>; <code>dropped</code> is reserved for supported resource types
+     * that were missing the subject/patient, code, or medication reference data
+     * needed to produce a valid row.</p>
      * <p>Each resource's primary clinical coding is resolved to a standard OMOP
      * <code>concept_id</code>. Alongside the OMOP rows grouped by table (<code>tables</code>), the
      * response carries <code>mappings</code> (how each source coding resolved, linked back

src/main/java/com/phenoml/api/resources/fhir2omop/AsyncRawFhir2OmopClient.java

@@ -41,6 +41,32 @@ public AsyncRawFhir2OmopClient(ClientOptions clientOptions) {
      * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows
      * (person, visit_occurrence, condition_occurrence, drug_exposure,
      * procedure_occurrence, measurement, observation).
+     * <p>Resource support is intentionally limited to the OMOP tables returned by
+     * this endpoint:</p>
+     * <ul>
+     * <li><code>Patient</code> -&gt; <code>person</code></li>
+     * <li><code>Encounter</code> -&gt; <code>visit_occurrence</code></li>
+     * <li><code>Condition</code> -&gt; <code>condition_occurrence</code></li>
+     * <li><code>Procedure</code> -&gt; <code>procedure_occurrence</code></li>
+     * <li><code>MedicationRequest</code>, <code>MedicationStatement</code>, and
+     * <code>MedicationAdministration</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Immunization</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Observation</code> with a numeric <code>valueQuantity</code>, <code>valueInteger</code>, or
+     * numeric-looking <code>valueString</code> (for example <code>&quot;&lt;2&quot;</code>) -&gt; <code>measurement</code></li>
+     * <li>non-numeric <code>Observation</code> -&gt; <code>observation</code></li>
+     * <li><code>AllergyIntolerance</code> -&gt; <code>observation</code></li>
+     * </ul>
+     * <p><code>Medication</code> is supported only as reference data for medication
+     * resources; it is not emitted as its own row because OMOP CDM has no
+     * Medication table. Other reference/admin resources such as <code>Practitioner</code>,
+     * <code>Organization</code>, <code>Location</code>, <code>Coverage</code>, and <code>Claim</code>, and clinical
+     * workflow/document resources such as <code>DiagnosticReport</code>, <code>ServiceRequest</code>,
+     * <code>CarePlan</code>, <code>DocumentReference</code>, <code>Composition</code>, <code>Specimen</code>, and
+     * <code>DeviceUseStatement</code>, are currently accepted in a Bundle but are not
+     * shaped into OMOP rows. Unsupported resource types are ignored rather than
+     * listed under <code>dropped</code>; <code>dropped</code> is reserved for supported resource types
+     * that were missing the subject/patient, code, or medication reference data
+     * needed to produce a valid row.</p>
      * <p>Each resource's primary clinical coding is resolved to a standard OMOP
      * <code>concept_id</code>. Alongside the OMOP rows grouped by table (<code>tables</code>), the
      * response carries <code>mappings</code> (how each source coding resolved, linked back
@@ -73,6 +99,32 @@ public CompletableFuture<PhenomlClientHttpResponse<CreateOmopResponse>> create(C
      * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows
      * (person, visit_occurrence, condition_occurrence, drug_exposure,
      * procedure_occurrence, measurement, observation).
+     * <p>Resource support is intentionally limited to the OMOP tables returned by
+     * this endpoint:</p>
+     * <ul>
+     * <li><code>Patient</code> -&gt; <code>person</code></li>
+     * <li><code>Encounter</code> -&gt; <code>visit_occurrence</code></li>
+     * <li><code>Condition</code> -&gt; <code>condition_occurrence</code></li>
+     * <li><code>Procedure</code> -&gt; <code>procedure_occurrence</code></li>
+     * <li><code>MedicationRequest</code>, <code>MedicationStatement</code>, and
+     * <code>MedicationAdministration</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Immunization</code> -&gt; <code>drug_exposure</code></li>
+     * <li><code>Observation</code> with a numeric <code>valueQuantity</code>, <code>valueInteger</code>, or
+     * numeric-looking <code>valueString</code> (for example <code>&quot;&lt;2&quot;</code>) -&gt; <code>measurement</code></li>
+     * <li>non-numeric <code>Observation</code> -&gt; <code>observation</code></li>
+     * <li><code>AllergyIntolerance</code> -&gt; <code>observation</code></li>
+     * </ul>
+     * <p><code>Medication</code> is supported only as reference data for medication
+     * resources; it is not emitted as its own row because OMOP CDM has no
+     * Medication table. Other reference/admin resources such as <code>Practitioner</code>,
+     * <code>Organization</code>, <code>Location</code>, <code>Coverage</code>, and <code>Claim</code>, and clinical
+     * workflow/document resources such as <code>DiagnosticReport</code>, <code>ServiceRequest</code>,
+     * <code>CarePlan</code>, <code>DocumentReference</code>, <code>Composition</code>, <code>Specimen</code>, and
+     * <code>DeviceUseStatement</code>, are currently accepted in a Bundle but are not
+     * shaped into OMOP rows. Unsupported resource types are ignored rather than
+     * listed under <code>dropped</code>; <code>dropped</code> is reserved for supported resource types
+     * that were missing the subject/patient, code, or medication reference data
+     * needed to produce a valid row.</p>
      * <p>Each resource's primary clinical coding is resolved to a standard OMOP
      * <code>concept_id</code>. Alongside the OMOP rows grouped by table (<code>tables</code>), the
      * response carries <code>mappings</code> (how each source coding resolved, linked back