@fhirfly-io/terminology 0.12.0 → 0.14.0

package/README.md

@@ -30,7 +30,7 @@ console.log(npi.data.name);
 ## Features
 
 - **Full TypeScript support** with comprehensive type definitions
-- **11 healthcare domains**: NDC, NPI, RxNorm, LOINC, ICD-10, CVX, MVX, FDA Labels, SNOMED CT, Connectivity, Claims
+- **17 healthcare domains**: NDC, NPI, RxNorm, LOINC, ICD-10, CVX, MVX, FDA Labels, SNOMED CT, UCUM, RxClass, HCPCS, MS-DRG, POS, J-Code/NDC Crosswalk, Connectivity, Claims
 - **Search** with full-text queries, filters, facets, and pagination
 - **Batch lookups** for efficient bulk operations
 - **Response shapes**: compact, standard, or full detail levels
@@ -246,6 +246,110 @@ const categories = await client.snomed.categories();
 const mappings = await client.snomed.mappings("73211009");
 ```
 
+### UCUM (Units of Measure)
+
+Unified Code for Units of Measure — lookup, validate, search, and convert healthcare units.
+
+```typescript
+// Look up a UCUM unit
+const unit = await client.ucum.lookup("mg");
+console.log(unit.data.display); // "milligram"
+
+// Validate a UCUM expression
+const validation = await client.ucum.validate("mg/dL");
+console.log(validation.data.is_valid); // true
+
+// Search for units
+const results = await client.ucum.search({ q: "milligram" });
+
+// Convert between units
+const conversion = await client.ucum.convert({
+  value: 1000,
+  from: "mg",
+  to: "g",
+});
+console.log(conversion.data.result); // 1
+```
+
+### RxClass (Drug Classifications)
+
+RxClass drug classification hierarchy from NLM — look up drug classes, search, and find class members.
+
+```typescript
+// Look up a drug class
+const rxclass = await client.rxclass.lookup("N0000175503");
+console.log(rxclass.data.class_name); // "HMG-CoA Reductase Inhibitors"
+
+// Search for drug classes
+const results = await client.rxclass.search({
+  q: "statin",
+  class_type: "EPC",
+});
+
+// Get members of a drug class (drugs belonging to the class)
+const members = await client.rxclass.members("N0000175503");
+for (const drug of members.data.members) {
+  console.log(`${drug.rxcui}: ${drug.name}`);
+}
+```
+
+### HCPCS Level II
+
+```typescript
+// Look up a procedure code
+const hcpcs = await client.hcpcs.lookup("A0425");
+console.log(hcpcs.data.short_description); // "Ground mileage, per statute mile"
+
+// Look up a modifier
+const mod = await client.hcpcs.lookupModifier("25");
+console.log(mod.data.short_description);
+
+// Batch lookup (up to 100)
+const results = await client.hcpcs.lookupMany(["A0425", "E0100"]);
+
+// Search
+const results = await client.hcpcs.search({ q: "ambulance" });
+```
+
+### MS-DRG (Diagnosis Related Groups)
+
+```typescript
+// Look up a DRG code
+const drg = await client.msdrg.lookup("470");
+console.log(drg.data.title); // "Major Joint Replacement..."
+
+// Search
+const results = await client.msdrg.search({
+  q: "cardiac",
+  type: "SURG",
+});
+```
+
+### POS (Place of Service)
+
+```typescript
+// Look up a POS code
+const pos = await client.pos.lookup("11");
+console.log(pos.data.name); // "Office"
+
+// List all POS codes (~52 total)
+const all = await client.pos.list();
+```
+
+### J-Code/NDC Crosswalk
+
+```typescript
+// J-code → NDCs (which NDCs map to this J-code?)
+const jcode = await client.jcode.byHcpcs("J9035");
+console.log(`${jcode.data.ndc_count} NDCs for ${jcode.data.hcpcs_description}`);
+
+// NDC → J-codes (which J-codes cover this NDC?)
+const reverse = await client.jcode.byNdc("00004110002");
+for (const entry of reverse.data.hcpcs_codes) {
+  console.log(`${entry.hcpcs_code}: ${entry.hcpcs_description}`);
+}
+```
+
 ### Connectivity Intelligence
 
 Discover how to reach a provider's organization electronically — FHIR endpoints, Direct addresses, and more.
@@ -310,11 +414,11 @@ All lookup and search methods accept a `shape` option to control response detail
 const ndc = await client.ndc.lookup("0069-0151-01", { shape: "full" });
 ```
 
-**Exceptions**: SNOMED always returns full data (no shapes). FDA Labels lookup uses a metadata + sections model instead of shapes; search uses shapes.
+**Exceptions**: SNOMED always returns full data (no shapes). FDA Labels lookup uses a metadata + sections model instead of shapes; search uses shapes. UCUM validate and convert return fixed result shapes (no shape parameter).
 
 ## Search
 
-All endpoints except Connectivity support full-text search with filters, facets, and pagination:
+All endpoints except Connectivity and RxClass members support full-text search with filters, facets, and pagination:
 
 ```typescript
 const results = await client.ndc.search(

package/dist/index.cjs

@@ -1590,6 +1590,342 @@ var DmdEndpoint = class {
   }
 };
 
+// src/endpoints/ucum.ts
+var UcumEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Look up a single UCUM unit code.
+   *
+   * @param code - UCUM unit code (e.g., "mg", "kg/m2", "mmol/L")
+   * @param options - Response shape and include options
+   * @returns UCUM unit data
+   *
+   * @example
+   * ```ts
+   * const unit = await client.ucum.lookup("mg");
+   * console.log(unit.data.display); // "milligram"
+   * ```
+   */
+  async lookup(code, options) {
+    return this.http.get(`/v1/ucum/${encodeURIComponent(code)}`, options);
+  }
+  /**
+   * Look up multiple UCUM unit codes in a single request.
+   *
+   * @param codes - Array of UCUM unit codes (max 100)
+   * @param options - Response shape, include, and batch options
+   * @returns Batch response with results for each code
+   */
+  async lookupMany(codes, options) {
+    if (codes.length === 0) throw new ValidationError("codes array must not be empty");
+    if (codes.length > 100) throw new ValidationError(`UCUM batch lookup supports max 100 codes, got ${codes.length}`);
+    return this.http.post(
+      "/v1/ucum/_batch",
+      { codes },
+      options
+    );
+  }
+  /**
+   * Search for UCUM units.
+   *
+   * @param params - Search parameters (q, kind, property, metric, is_common_clinical)
+   * @param options - Pagination and response shape options
+   * @returns Search results with facets
+   *
+   * @example
+   * ```ts
+   * // Search for mass units
+   * const results = await client.ucum.search({ q: "gram" });
+   *
+   * // Find common clinical units for length
+   * const results = await client.ucum.search({
+   *   kind: "length",
+   *   is_common_clinical: true
+   * });
+   * ```
+   */
+  async search(params, options) {
+    return this.http.search("/v1/ucum/search", {
+      ...params,
+      ...options,
+      include: options?.include?.join(",")
+    });
+  }
+  /**
+   * Validate a UCUM expression.
+   *
+   * Checks whether a UCUM expression is syntactically valid and all
+   * component unit codes are recognized.
+   *
+   * @param expression - UCUM expression to validate (e.g., "mg/dL", "kg.m-2")
+   * @returns Validation result with component breakdown
+   *
+   * @example
+   * ```ts
+   * const result = await client.ucum.validate("mg/dL");
+   * console.log(result.data.valid); // true
+   *
+   * const invalid = await client.ucum.validate("xyz123");
+   * console.log(invalid.data.valid); // false
+   * console.log(invalid.data.error); // description of the problem
+   * ```
+   */
+  async validate(expression) {
+    return this.http.get(
+      `/v1/ucum/validate/${encodeURIComponent(expression)}`
+    );
+  }
+  /**
+   * Convert a value between UCUM units.
+   *
+   * Converts a numeric value from one UCUM unit to another compatible unit.
+   * Both units must measure the same physical quantity (e.g., both mass,
+   * both length).
+   *
+   * @param from - Source UCUM unit code
+   * @param to - Target UCUM unit code
+   * @param value - Numeric value to convert
+   * @returns Conversion result with factor
+   *
+   * @example
+   * ```ts
+   * // Convert 5 kilograms to pounds
+   * const result = await client.ucum.convert("kg", "[lb_av]", 5);
+   * console.log(result.data.to.value); // ~11.0231
+   *
+   * // Convert temperature: 98.6 Fahrenheit to Celsius
+   * const temp = await client.ucum.convert("[degF]", "Cel", 98.6);
+   * console.log(temp.data.to.value); // 37
+   * ```
+   */
+  async convert(from, to, value) {
+    return this.http.search("/v1/ucum/convert", {
+      from,
+      to,
+      value
+    });
+  }
+};
+
+// src/endpoints/rxclass.ts
+var RxClassEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Look up a single RxClass drug class.
+   *
+   * @param classId - RxClass identifier
+   * @param options - Response shape and include options
+   * @returns RxClass data
+   *
+   * @example
+   * ```ts
+   * const cls = await client.rxclass.lookup("N0000175557");
+   * console.log(cls.data.class_name); // "HMG-CoA Reductase Inhibitors"
+   * ```
+   */
+  async lookup(classId, options) {
+    return this.http.get(`/v1/rxclass/${encodeURIComponent(classId)}`, options);
+  }
+  /**
+   * Look up multiple RxClass drug classes in a single request.
+   *
+   * @param classIds - Array of RxClass identifiers (max 100)
+   * @param options - Response shape, include, and batch options
+   * @returns Batch response with results for each class ID
+   */
+  async lookupMany(classIds, options) {
+    if (classIds.length === 0) throw new ValidationError("classIds array must not be empty");
+    if (classIds.length > 100) throw new ValidationError(`RxClass batch lookup supports max 100 codes, got ${classIds.length}`);
+    return this.http.post(
+      "/v1/rxclass/_batch",
+      { codes: classIds },
+      options
+    );
+  }
+  /**
+   * Search for drug classes.
+   *
+   * @param params - Search parameters (q, class_type)
+   * @param options - Pagination and response shape options
+   * @returns Search results with facets
+   *
+   * @example
+   * ```ts
+   * // Search for statin-related classes
+   * const results = await client.rxclass.search({ q: "statin" });
+   *
+   * // Find all EPC (Established Pharmacologic Class) entries
+   * const results = await client.rxclass.search({
+   *   class_type: "EPC"
+   * });
+   * ```
+   */
+  async search(params, options) {
+    return this.http.search("/v1/rxclass/search", {
+      ...params,
+      ...options,
+      include: options?.include?.join(",")
+    });
+  }
+  /**
+   * Get member drugs of a drug class.
+   *
+   * Returns the list of RxNorm concepts (RxCUIs) that belong to the
+   * specified drug class.
+   *
+   * @param classId - RxClass identifier
+   * @param options - Response shape and include options
+   * @returns Members response with array of RxCUI members
+   *
+   * @example
+   * ```ts
+   * // Get all drugs in a class
+   * const members = await client.rxclass.members("N0000175557");
+   * console.log(members.data.count); // number of member drugs
+   * console.log(members.data.members); // [{ rxcui: "...", name: "..." }, ...]
+   * ```
+   */
+  async members(classId, options) {
+    return this.http.get(
+      `/v1/rxclass/${encodeURIComponent(classId)}/members`,
+      options
+    );
+  }
+};
+
+// src/endpoints/hcpcs.ts
+var HcpcsEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async lookup(code, options) {
+    return this.http.get(`/v1/hcpcs/${encodeURIComponent(code)}`, options);
+  }
+  async lookupModifier(code, options) {
+    return this.http.get(`/v1/hcpcs/modifier/${encodeURIComponent(code)}`, options);
+  }
+  async lookupMany(codes, options) {
+    if (codes.length === 0) throw new ValidationError("codes array must not be empty");
+    if (codes.length > 100) throw new ValidationError(`HCPCS batch lookup supports max 100 codes, got ${codes.length}`);
+    return this.http.post("/v1/hcpcs/_batch", { codes }, options);
+  }
+  async search(params, options) {
+    return this.http.search("/v1/hcpcs/search", {
+      ...params,
+      ...options,
+      include: options?.include?.join(",")
+    });
+  }
+};
+
+// src/endpoints/msdrg.ts
+var MsdrgEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async lookup(code, options) {
+    return this.http.get(`/v1/msdrg/${encodeURIComponent(code)}`, options);
+  }
+  async lookupMany(codes, options) {
+    if (codes.length === 0) throw new ValidationError("codes array must not be empty");
+    if (codes.length > 100) throw new ValidationError(`MS-DRG batch lookup supports max 100 codes, got ${codes.length}`);
+    return this.http.post("/v1/msdrg/_batch", { codes }, options);
+  }
+  async search(params, options) {
+    return this.http.search("/v1/msdrg/search", {
+      ...params,
+      ...options,
+      include: options?.include?.join(",")
+    });
+  }
+};
+
+// src/endpoints/pos.ts
+var PosEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async lookup(code, options) {
+    return this.http.get(`/v1/pos/${encodeURIComponent(code)}`, options);
+  }
+  async lookupMany(codes, options) {
+    if (codes.length === 0) throw new ValidationError("codes array must not be empty");
+    if (codes.length > 100) throw new ValidationError(`POS batch lookup supports max 100 codes, got ${codes.length}`);
+    return this.http.post("/v1/pos/_batch", { codes }, options);
+  }
+  /**
+   * List all Place of Service codes (~52 codes).
+   */
+  async list(options) {
+    return this.http.get("/v1/pos/list", options);
+  }
+};
+
+// src/endpoints/jcode.ts
+var JcodeEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Look up NDC codes for a HCPCS J-code.
+   * @param code - HCPCS code (J, Q, A, C codes or 5-digit numeric)
+   */
+  async byHcpcs(code) {
+    return this.http.get(`/v1/jcode/by-hcpcs/${encodeURIComponent(code)}`);
+  }
+  /**
+   * Reverse lookup: find HCPCS codes for an NDC.
+   * @param ndc - NDC code (11 digits, with or without dashes)
+   */
+  async byNdc(ndc) {
+    return this.http.get(`/v1/jcode/by-ndc/${encodeURIComponent(ndc)}`);
+  }
+};
+
+// src/endpoints/ddi.ts
+var DdiEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Look up interaction reference data for a single drug.
+   * @param identifier - RxCUI, drug name, or NDC code
+   * @param options - Optional settings (e.g., filter to specific label sections)
+   */
+  async reference(identifier, options) {
+    let path = `/v1/ddi/reference/${encodeURIComponent(identifier)}`;
+    if (options?.sections?.length) {
+      const params = new URLSearchParams();
+      params.set("sections", options.sections.join(","));
+      path += `?${params.toString()}`;
+    }
+    return this.http.get(path);
+  }
+  /**
+   * Look up interaction reference data for multiple drugs.
+   * @param drugs - Array of RxCUI, drug name, or NDC identifiers (max 25)
+   * @param options - Optional settings (e.g., filter to specific label sections)
+   * @throws {ValidationError} If drugs array is empty or exceeds 25 items
+   */
+  async referenceMany(drugs, options) {
+    if (drugs.length === 0) {
+      throw new ValidationError("At least one drug identifier is required");
+    }
+    if (drugs.length > 25) {
+      throw new ValidationError(`Batch size ${drugs.length} exceeds maximum of 25 drugs`);
+    }
+    const body = { drugs };
+    if (options?.sections?.length) {
+      body.sections = options.sections;
+    }
+    return this.http.post("/v1/ddi/reference", body);
+  }
+};
+
 // src/client.ts
 var Fhirfly = class {
   http;
@@ -1660,6 +1996,40 @@ var Fhirfly = class {
    * UK NHS medicines reference data standard covering VTM/VMP/AMP/VMPP/AMPP.
    */
   dmd;
+  /**
+   * UCUM (Unified Code for Units of Measure) lookups.
+   * Standardized units of measure for healthcare and science, with validation and conversion.
+   */
+  ucum;
+  /**
+   * RxClass drug classification hierarchy lookups.
+   * ATC, EPC, MOA, PE, and CHEM drug class types with member drug listings.
+   */
+  rxclass;
+  /**
+   * HCPCS Level II procedure and supply code lookups.
+   * CMS codes for non-physician services, supplies, and equipment.
+   */
+  hcpcs;
+  /**
+   * MS-DRG (Medicare Severity Diagnosis Related Group) lookups.
+   * Inpatient hospital payment classifications with weights and length of stay.
+   */
+  msdrg;
+  /**
+   * Place of Service code lookups.
+   * CMS codes identifying where healthcare services were rendered.
+   */
+  pos;
+  /**
+   * J-Code/NDC crosswalk lookups.
+   * Bidirectional mapping between HCPCS J-codes and NDC drug codes.
+   */
+  jcode;
+  /**
+   * Drug-Drug Interaction reference — FDA label interaction text + RxNorm enrichment.
+   */
+  ddi;
   /**
    * Create a new FHIRfly client.
    *
@@ -1712,23 +2082,37 @@ var Fhirfly = class {
     this.hcc = new HccEndpoint(this.http);
     this.opcs4 = new Opcs4Endpoint(this.http);
     this.dmd = new DmdEndpoint(this.http);
+    this.ucum = new UcumEndpoint(this.http);
+    this.rxclass = new RxClassEndpoint(this.http);
+    this.hcpcs = new HcpcsEndpoint(this.http);
+    this.msdrg = new MsdrgEndpoint(this.http);
+    this.pos = new PosEndpoint(this.http);
+    this.jcode = new JcodeEndpoint(this.http);
+    this.ddi = new DdiEndpoint(this.http);
   }
 };
 
 exports.ApiError = ApiError;
 exports.AuthenticationError = AuthenticationError;
+exports.DdiEndpoint = DdiEndpoint;
 exports.DmdEndpoint = DmdEndpoint;
 exports.Fhirfly = Fhirfly;
 exports.FhirflyError = FhirflyError;
 exports.HccEndpoint = HccEndpoint;
+exports.HcpcsEndpoint = HcpcsEndpoint;
+exports.JcodeEndpoint = JcodeEndpoint;
+exports.MsdrgEndpoint = MsdrgEndpoint;
 exports.NetworkError = NetworkError;
 exports.NotFoundError = NotFoundError;
 exports.Opcs4Endpoint = Opcs4Endpoint;
+exports.PosEndpoint = PosEndpoint;
 exports.QuotaExceededError = QuotaExceededError;
 exports.RateLimitError = RateLimitError;
+exports.RxClassEndpoint = RxClassEndpoint;
 exports.ServerError = ServerError;
 exports.TimeoutError = TimeoutError;
 exports.TokenManager = TokenManager;
+exports.UcumEndpoint = UcumEndpoint;
 exports.ValidationError = ValidationError;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map