@fhirfly-io/terminology 0.7.0 → 0.8.0

package/dist/index.js

@@ -169,7 +169,7 @@ var HttpClient = class {
       timeout: config.timeout ?? 3e4,
       maxRetries: config.maxRetries ?? 3,
       retryDelay: config.retryDelay ?? 1e3,
-      userAgent: config.userAgent ?? `@fhirfly/sdk/0.1.0 Node.js/${process.version}`
+      userAgent: config.userAgent ?? `@fhirfly-io/terminology/0.7.1 Node.js/${process.version}`
     };
   }
   /**
@@ -306,7 +306,7 @@ var HttpClient = class {
           if (response.status === 429) {
             const retryAfter = response.headers.get("retry-after");
             if (retryAfter && attempt < this.config.maxRetries) {
-              await this.sleep(parseInt(retryAfter, 10) * 1e3);
+              await this.sleep(Math.min(parseInt(retryAfter, 10) * 1e3, 12e4));
               continue;
             }
             await this.parseErrorResponse(response, endpoint);
@@ -385,7 +385,7 @@ var NdcEndpoint = class {
    * @example
    * ```ts
    * const ndc = await client.ndc.lookup("0069-0151-01");
-   * console.log(ndc.data.product_name); // "Lipitor"
+   * console.log(ndc.data.brand_name); // "Lipitor"
    * ```
    */
   async lookup(code, options) {
@@ -407,15 +407,17 @@ var NdcEndpoint = class {
    * ]);
    *
    * for (const item of results.results) {
-   *   if (item.found) {
-   *     console.log(item.data.product_name);
+   *   if (item.status === "ok") {
+   *     console.log(item.data.brand_name);
    *   } else {
-   *     console.log(`Not found: ${item.code}`);
+   *     console.log(`Not found: ${item.input}`);
    *   }
    * }
    * ```
    */
   async lookupMany(codes, options) {
+    if (codes.length === 0) throw new ValidationError("codes array must not be empty");
+    if (codes.length > 500) throw new ValidationError(`NDC batch lookup supports max 500 codes, got ${codes.length}`);
     return this.http.post(
       "/v1/ndc/_batch",
       { codes },
@@ -480,7 +482,7 @@ var NpiEndpoint = class {
   /**
    * Look up multiple NPIs in a single request.
    *
-   * @param npis - Array of 10-digit NPI numbers (max 500)
+   * @param npis - Array of 10-digit NPI numbers (max 100)
    * @param options - Response shape, include, and batch options
    * @returns Batch response with results for each NPI
    *
@@ -493,6 +495,8 @@ var NpiEndpoint = class {
    * ```
    */
   async lookupMany(npis, options) {
+    if (npis.length === 0) throw new ValidationError("npis array must not be empty");
+    if (npis.length > 100) throw new ValidationError(`NPI batch lookup supports max 100 codes, got ${npis.length}`);
     return this.http.post(
       "/v1/npi/_batch",
       { codes: npis },
@@ -554,11 +558,13 @@ var RxNormEndpoint = class {
   /**
    * Look up multiple RxCUIs in a single request.
    *
-   * @param rxcuis - Array of RxCUIs (max 500)
+   * @param rxcuis - Array of RxCUIs (max 100)
    * @param options - Response shape, include, and batch options
    * @returns Batch response with results for each RxCUI
    */
   async lookupMany(rxcuis, options) {
+    if (rxcuis.length === 0) throw new ValidationError("rxcuis array must not be empty");
+    if (rxcuis.length > 100) throw new ValidationError(`RxNorm batch lookup supports max 100 codes, got ${rxcuis.length}`);
     return this.http.post(
       "/v1/rxnorm/_batch",
       { codes: rxcuis },
@@ -617,11 +623,13 @@ var LoincEndpoint = class {
   /**
    * Look up multiple LOINC codes in a single request.
    *
-   * @param loincNums - Array of LOINC numbers (max 500)
+   * @param loincNums - Array of LOINC numbers (max 100)
    * @param options - Response shape, include, and batch options
    * @returns Batch response with results for each LOINC
    */
   async lookupMany(loincNums, options) {
+    if (loincNums.length === 0) throw new ValidationError("loincNums array must not be empty");
+    if (loincNums.length > 100) throw new ValidationError(`LOINC batch lookup supports max 100 codes, got ${loincNums.length}`);
     return this.http.post(
       "/v1/loinc/_batch",
       { codes: loincNums },
@@ -691,11 +699,13 @@ var Icd10Endpoint = class {
    *
    * Codes can be a mix of CM (diagnoses) and PCS (procedures).
    *
-   * @param codes - Array of ICD-10 codes (max 500)
+   * @param codes - Array of ICD-10 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(`ICD-10 batch lookup supports max 100 codes, got ${codes.length}`);
     return this.http.post(
       "/v1/icd10/_batch",
       { codes },
@@ -758,11 +768,13 @@ var CvxEndpoint = class {
   /**
    * Look up multiple CVX codes in a single request.
    *
-   * @param cvxCodes - Array of CVX codes (max 500)
+   * @param cvxCodes - Array of CVX codes (max 100)
    * @param options - Response shape, include, and batch options
    * @returns Batch response with results for each code
    */
   async lookupMany(cvxCodes, options) {
+    if (cvxCodes.length === 0) throw new ValidationError("cvxCodes array must not be empty");
+    if (cvxCodes.length > 100) throw new ValidationError(`CVX batch lookup supports max 100 codes, got ${cvxCodes.length}`);
     return this.http.post(
       "/v1/cvx/_batch",
       { codes: cvxCodes },
@@ -821,11 +833,13 @@ var MvxEndpoint = class {
   /**
    * Look up multiple MVX codes in a single request.
    *
-   * @param mvxCodes - Array of MVX codes (max 500)
+   * @param mvxCodes - Array of MVX codes (max 100)
    * @param options - Response shape, include, and batch options
    * @returns Batch response with results for each code
    */
   async lookupMany(mvxCodes, options) {
+    if (mvxCodes.length === 0) throw new ValidationError("mvxCodes array must not be empty");
+    if (mvxCodes.length > 100) throw new ValidationError(`MVX batch lookup supports max 100 codes, got ${mvxCodes.length}`);
     return this.http.post(
       "/v1/mvx/_batch",
       { codes: mvxCodes },
@@ -907,10 +921,12 @@ var FdaLabelsEndpoint = class {
    * Returns metadata only (no sections) for batch efficiency.
    * Identifiers can be Set IDs, NDC codes, or RxCUIs (mixed).
    *
-   * @param identifiers - Array of identifiers (max 500)
+   * @param identifiers - Array of identifiers (max 50)
    * @returns Batch response with results for each identifier
    */
   async lookupMany(identifiers) {
+    if (identifiers.length === 0) throw new ValidationError("identifiers array must not be empty");
+    if (identifiers.length > 50) throw new ValidationError(`FDA Labels batch lookup supports max 50 identifiers, got ${identifiers.length}`);
     return this.http.post(
       "/v1/fda-label/_batch",
       { codes: identifiers }
@@ -1032,6 +1048,8 @@ var SnomedEndpoint = class {
    * ```
    */
   async lookupMany(conceptIds) {
+    if (conceptIds.length === 0) throw new ValidationError("conceptIds array must not be empty");
+    if (conceptIds.length > 100) throw new ValidationError(`SNOMED batch lookup supports max 100 codes, got ${conceptIds.length}`);
     return this.http.post(
       "/v1/snomed/_batch",
       { codes: conceptIds }
@@ -1098,6 +1116,168 @@ var SnomedEndpoint = class {
   }
 };
 
+// src/endpoints/claims.ts
+var ClaimsEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  // ==========================================================================
+  // NCCI PTP Edits
+  // ==========================================================================
+  /**
+   * Validate whether two CPT/HCPCS codes can be billed together.
+   *
+   * @param code1 - First CPT/HCPCS code (4-5 alphanumeric characters)
+   * @param code2 - Second CPT/HCPCS code (4-5 alphanumeric characters)
+   * @param options - Optional filters (claim_type)
+   * @returns Validation result with edit details and billing summary
+   *
+   * @example
+   * ```ts
+   * const result = await client.claims.validateNcci("99213", "99214");
+   * if (!result.data.can_bill_together) {
+   *   console.log(result.data.summary);
+   *   for (const edit of result.data.edits) {
+   *     console.log(`${edit.claim_type}: modifier ${edit.modifier_allowed ? "allowed" : "not allowed"}`);
+   *   }
+   * }
+   * ```
+   */
+  async validateNcci(code1, code2, options) {
+    const params = {
+      code1: encodeURIComponent(code1),
+      code2: encodeURIComponent(code2)
+    };
+    if (options?.claim_type) {
+      params.claim_type = options.claim_type;
+    }
+    const queryString = this.http.buildSearchQueryString(params);
+    return this.http.get(`/v1/ncci/validate${queryString}`);
+  }
+  // ==========================================================================
+  // MUE (Medically Unlikely Edits)
+  // ==========================================================================
+  /**
+   * Look up MUE limits for a HCPCS/CPT code.
+   *
+   * @param hcpcs - HCPCS/CPT code (4-5 alphanumeric characters)
+   * @param options - Optional filters (service_type)
+   * @returns MUE limit data including max units per service type
+   *
+   * @example
+   * ```ts
+   * const mue = await client.claims.lookupMue("99213");
+   * for (const limit of mue.data.limits) {
+   *   console.log(`${limit.service_type}: max ${limit.mue_value} units`);
+   * }
+   * ```
+   */
+  async lookupMue(hcpcs, options) {
+    const params = {};
+    if (options?.service_type) {
+      params.service_type = options.service_type;
+    }
+    const queryString = this.http.buildSearchQueryString(params);
+    return this.http.get(
+      `/v1/mue/${encodeURIComponent(hcpcs)}${queryString}`
+    );
+  }
+  /**
+   * Batch MUE lookup for multiple HCPCS codes.
+   *
+   * @param codes - Array of HCPCS/CPT codes (max 100)
+   * @returns Batch results with per-code MUE limits
+   *
+   * @example
+   * ```ts
+   * const results = await client.claims.lookupMueMany(["99213", "99214", "99215"]);
+   * for (const item of results.results) {
+   *   if (item.status === "ok") {
+   *     console.log(`${item.hcpcs_code}: ${item.data.limits.length} limits`);
+   *   }
+   * }
+   * ```
+   */
+  async lookupMueMany(codes) {
+    if (codes.length === 0) throw new ValidationError("codes array must not be empty");
+    if (codes.length > 100) throw new ValidationError(`MUE batch lookup supports max 100 codes, got ${codes.length}`);
+    return this.http.post("/v1/mue/_batch", { codes });
+  }
+  // ==========================================================================
+  // PFS/RVU (Physician Fee Schedule / Relative Value Units)
+  // ==========================================================================
+  /**
+   * Look up Physician Fee Schedule and RVU data for a HCPCS/CPT code.
+   *
+   * @param hcpcs - HCPCS/CPT code (4-5 alphanumeric characters)
+   * @returns Fee schedule data including RVU breakdown and calculated payments
+   *
+   * @example
+   * ```ts
+   * const pfs = await client.claims.lookupPfs("99213");
+   * console.log(`Description: ${pfs.data.description}`);
+   * console.log(`Work RVU: ${pfs.data.rvu.work}`);
+   * console.log(`Non-facility payment: $${pfs.data.calculated_payment.non_facility}`);
+   * console.log(`Facility payment: $${pfs.data.calculated_payment.facility}`);
+   * ```
+   */
+  async lookupPfs(hcpcs) {
+    return this.http.get(
+      `/v1/pfs/${encodeURIComponent(hcpcs)}`
+    );
+  }
+  /**
+   * Batch PFS/RVU lookup for multiple HCPCS codes.
+   *
+   * @param codes - Array of HCPCS/CPT codes (max 100)
+   * @returns Batch results with per-code fee schedule data
+   *
+   * @example
+   * ```ts
+   * const results = await client.claims.lookupPfsMany(["99213", "99214", "99215"]);
+   * for (const item of results.results) {
+   *   if (item.status === "ok") {
+   *     console.log(`${item.hcpcs_code}: $${item.data.calculated_payment.non_facility}`);
+   *   }
+   * }
+   * ```
+   */
+  async lookupPfsMany(codes) {
+    if (codes.length === 0) throw new ValidationError("codes array must not be empty");
+    if (codes.length > 100) throw new ValidationError(`PFS batch lookup supports max 100 codes, got ${codes.length}`);
+    return this.http.post("/v1/pfs/_batch", { codes });
+  }
+  // ==========================================================================
+  // LCD/NCD Coverage Determination
+  // ==========================================================================
+  /**
+   * Check LCD/NCD coverage determinations linked to a HCPCS code.
+   *
+   * @param hcpcs - HCPCS/CPT code (4-5 alphanumeric characters)
+   * @param options - Optional filters (active only)
+   * @returns Coverage policies linked to the code
+   *
+   * @example
+   * ```ts
+   * const coverage = await client.claims.checkCoverage("99213");
+   * console.log(`${coverage.data.policies_found} policies found`);
+   * for (const policy of coverage.data.policies) {
+   *   console.log(`${policy.display_id}: ${policy.policy_title} [${policy.status}]`);
+   * }
+   * ```
+   */
+  async checkCoverage(hcpcs, options) {
+    const params = {
+      hcpcs: encodeURIComponent(hcpcs)
+    };
+    if (options?.active !== void 0) {
+      params.active = options.active.toString();
+    }
+    const queryString = this.http.buildSearchQueryString(params);
+    return this.http.get(`/v1/coverage/check${queryString}`);
+  }
+};
+
 // src/client.ts
 var Fhirfly = class {
   http;
@@ -1143,6 +1323,11 @@ var Fhirfly = class {
    * Look up clinical concepts from the SNOMED CT IPS free set (~12K concepts, CC BY 4.0).
    */
   snomed;
+  /**
+   * Claims Intelligence endpoints (requires `claims.read` scope).
+   * NCCI PTP validation, MUE limits, PFS/RVU fee schedule, LCD/NCD coverage.
+   */
+  claims;
   /**
    * Create a new FHIRfly client.
    *
@@ -1190,6 +1375,7 @@ var Fhirfly = class {
     this.fdaLabels = new FdaLabelsEndpoint(this.http);
     this.connectivity = new ConnectivityEndpoint(this.http);
     this.snomed = new SnomedEndpoint(this.http);
+    this.claims = new ClaimsEndpoint(this.http);
   }
 };