@fhirfly-io/terminology 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -18,10 +18,7 @@ interface LookupOptions {
 /**
  * Common options for batch lookup methods.
  */
-interface BatchLookupOptions extends LookupOptions {
-    /** Maximum codes per batch (default: 100, max: 500) */
-    batchSize?: number;
-}
+type BatchLookupOptions = LookupOptions;
 /**
  * Legal/licensing information included in responses.
  */
@@ -467,7 +464,7 @@ declare class NdcEndpoint {
      * @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"
      * ```
      */
     lookup(code: string, options?: LookupOptions): Promise<ApiResponse<NdcData>>;
@@ -487,10 +484,10 @@ declare class NdcEndpoint {
      * ]);
      *
      * 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}`);
      *   }
      * }
      * ```
@@ -533,18 +530,19 @@ interface PersonName {
     middle?: string;
     prefix?: string;
     suffix?: string;
-    credential?: string;
+    credential_text?: string;
+    sex?: string;
 }
 /**
  * Provider address information.
  */
 interface NpiAddress {
-    address_1?: string;
-    address_2?: string;
+    line1?: string;
+    line2?: string;
     city?: string;
     state?: string;
-    postal_code?: string;
-    country_code?: string;
+    postal?: string;
+    country?: string;
     phone?: string;
     phone_digits?: string;
     fax?: string;
@@ -716,7 +714,7 @@ declare class NpiEndpoint {
     /**
      * 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
      *
@@ -858,7 +856,7 @@ declare class RxNormEndpoint {
     /**
      * 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
      */
@@ -1035,7 +1033,7 @@ declare class LoincEndpoint {
     /**
      * 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
      */
@@ -1178,7 +1176,7 @@ declare class Icd10Endpoint {
      *
      * 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
      */
@@ -1277,7 +1275,7 @@ declare class CvxEndpoint {
     /**
      * 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
      */
@@ -1404,7 +1402,7 @@ declare class MvxEndpoint {
     /**
      * 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
      */
@@ -1586,7 +1584,7 @@ declare class FdaLabelsEndpoint {
      * 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
      */
     lookupMany(identifiers: string[]): Promise<BatchResponse<FdaLabelData>>;
@@ -1933,6 +1931,367 @@ declare class SnomedEndpoint {
     mappings(conceptId: string): Promise<ApiResponse<SnomedReverseMappingData>>;
 }
 
+/**
+ * Claim type for NCCI PTP edits.
+ */
+type NcciClaimType = "practitioner" | "hospital";
+/**
+ * MUE service type.
+ */
+type MueServiceType = "practitioner" | "outpatient_hospital" | "dme";
+/**
+ * Coverage policy type.
+ */
+type CoveragePolicyType = "lcd" | "ncd";
+/**
+ * Legal information for claims responses.
+ */
+interface ClaimsLegalInfo {
+    license: string;
+    attribution_required: boolean;
+    source_name: string;
+    citation: string;
+}
+/**
+ * Metadata included in claims API responses.
+ */
+interface ClaimsMeta {
+    source: {
+        name: string;
+        quarter?: string;
+        url?: string;
+    };
+    legal: ClaimsLegalInfo;
+}
+/**
+ * Individual NCCI PTP edit result.
+ */
+interface NcciEditItem {
+    claim_type: NcciClaimType;
+    modifier_indicator: string;
+    modifier_allowed: boolean;
+    effective_date: string | null;
+    is_active: boolean;
+    rationale: string;
+}
+/**
+ * NCCI PTP validation data.
+ */
+interface NcciValidateData {
+    code1: string;
+    code2: string;
+    can_bill_together: boolean;
+    edits: NcciEditItem[];
+    summary: string;
+}
+/**
+ * NCCI PTP validation response.
+ */
+interface NcciValidateResponse {
+    data: NcciValidateData;
+    meta: ClaimsMeta;
+}
+/**
+ * Individual MUE limit entry.
+ */
+interface MueLimitItem {
+    hcpcs_code: string;
+    service_type: string;
+    mue_value: number;
+    adjudication_indicator: number;
+    adjudication_indicator_display: string;
+    rationale: string;
+}
+/**
+ * MUE lookup data.
+ */
+interface MueLookupData {
+    hcpcs_code: string;
+    limits: MueLimitItem[];
+}
+/**
+ * MUE single lookup response.
+ */
+interface MueLookupResponse {
+    data: MueLookupData;
+    meta: ClaimsMeta;
+}
+/**
+ * MUE batch result item.
+ */
+interface MueBatchResultItem {
+    input: string;
+    hcpcs_code: string;
+    status: "ok" | "not_found" | "invalid";
+    data?: MueLookupData;
+    error?: string;
+}
+/**
+ * MUE batch response.
+ */
+interface MueBatchResponse {
+    count: number;
+    results: MueBatchResultItem[];
+    meta: {
+        legal: ClaimsLegalInfo;
+    };
+}
+/**
+ * RVU breakdown values.
+ */
+interface PfsRvu {
+    work: number;
+    pe_non_facility: number;
+    pe_facility: number;
+    mp: number;
+    total_non_facility: number;
+    total_facility: number;
+}
+/**
+ * Calculated payment amounts.
+ */
+interface PfsPayment {
+    non_facility: number;
+    facility: number;
+}
+/**
+ * PFS billing indicators.
+ */
+interface PfsIndicators {
+    global_days: string | null;
+    multiple_surgery: string | null;
+    bilateral_surgery: string | null;
+}
+/**
+ * PFS/RVU lookup data for a single HCPCS code.
+ */
+interface PfsLookupData {
+    hcpcs_code: string;
+    description: string;
+    status_code: string;
+    rvu: PfsRvu;
+    conversion_factor: number;
+    calculated_payment: PfsPayment;
+    indicators: PfsIndicators;
+}
+/**
+ * PFS single lookup response.
+ */
+interface PfsLookupResponse {
+    data: PfsLookupData;
+    meta: ClaimsMeta;
+}
+/**
+ * PFS batch result item.
+ */
+interface PfsBatchResultItem {
+    input: string;
+    hcpcs_code: string;
+    status: "ok" | "not_found" | "invalid";
+    data?: PfsLookupData;
+    error?: string;
+}
+/**
+ * PFS batch response.
+ */
+interface PfsBatchResponse {
+    count: number;
+    results: PfsBatchResultItem[];
+    meta: {
+        legal: ClaimsLegalInfo;
+    };
+}
+/**
+ * Individual coverage policy item.
+ */
+interface CoverageCheckItem {
+    policy_type: CoveragePolicyType;
+    policy_id: string;
+    display_id: string;
+    policy_title: string;
+    hcpcs_description: string;
+    status: string;
+    is_active: boolean;
+    effective_date: string | null;
+}
+/**
+ * Coverage check data.
+ */
+interface CoverageCheckData {
+    hcpcs_code: string;
+    policies_found: number;
+    policies: CoverageCheckItem[];
+    summary: string;
+}
+/**
+ * Coverage check response.
+ */
+interface CoverageCheckResponse {
+    data: CoverageCheckData;
+    meta: ClaimsMeta;
+}
+
+/**
+ * Options for NCCI PTP validation.
+ */
+interface NcciValidateOptions {
+    /** Filter by claim type. If omitted, returns edits for all claim types. */
+    claim_type?: NcciClaimType;
+}
+/**
+ * Options for MUE lookup.
+ */
+interface MueLookupOptions {
+    /** Filter by service type. If omitted, returns limits for all service types. */
+    service_type?: MueServiceType;
+}
+/**
+ * Options for coverage check.
+ */
+interface CoverageCheckOptions {
+    /** Return only active policies. Default: true */
+    active?: boolean;
+}
+/**
+ * Claims Intelligence API endpoints.
+ *
+ * Provides access to CMS claims editing and payment data:
+ * - **NCCI PTP**: Validate if two CPT/HCPCS codes can be billed together
+ * - **MUE**: Look up Medically Unlikely Edit limits for HCPCS codes
+ * - **PFS/RVU**: Look up Physician Fee Schedule and Relative Value Units
+ * - **Coverage**: Check LCD/NCD coverage determinations for HCPCS codes
+ *
+ * All claims endpoints require the `claims.read` scope.
+ *
+ * @example
+ * ```ts
+ * // Check if two codes can be billed together
+ * const ncci = await client.claims.validateNcci("99213", "99214");
+ * console.log(ncci.data.can_bill_together);
+ *
+ * // Look up MUE limits
+ * const mue = await client.claims.lookupMue("99213");
+ * for (const limit of mue.data.limits) {
+ *   console.log(`${limit.service_type}: max ${limit.mue_value} units`);
+ * }
+ *
+ * // Look up fee schedule / RVU data
+ * const pfs = await client.claims.lookupPfs("99213");
+ * console.log(`Payment: $${pfs.data.calculated_payment.non_facility}`);
+ *
+ * // Check coverage policies
+ * const coverage = await client.claims.checkCoverage("99213");
+ * console.log(`${coverage.data.policies_found} policies found`);
+ * ```
+ */
+declare class ClaimsEndpoint {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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"}`);
+     *   }
+     * }
+     * ```
+     */
+    validateNcci(code1: string, code2: string, options?: NcciValidateOptions): Promise<NcciValidateResponse>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    lookupMue(hcpcs: string, options?: MueLookupOptions): Promise<MueLookupResponse>;
+    /**
+     * 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`);
+     *   }
+     * }
+     * ```
+     */
+    lookupMueMany(codes: string[]): Promise<MueBatchResponse>;
+    /**
+     * 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}`);
+     * ```
+     */
+    lookupPfs(hcpcs: string): Promise<PfsLookupResponse>;
+    /**
+     * 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}`);
+     *   }
+     * }
+     * ```
+     */
+    lookupPfsMany(codes: string[]): Promise<PfsBatchResponse>;
+    /**
+     * 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}]`);
+     * }
+     * ```
+     */
+    checkCoverage(hcpcs: string, options?: CoverageCheckOptions): Promise<CoverageCheckResponse>;
+}
+
 /**
  * Base configuration options shared by all auth modes.
  */
@@ -2005,11 +2364,12 @@ type FhirflyConfig = FhirflyApiKeyConfig | FhirflyOAuthConfig;
  *
  * Provides access to healthcare reference data including drug codes (NDC, RxNorm),
  * provider identifiers (NPI), lab codes (LOINC), diagnosis codes (ICD-10),
- * vaccine codes (CVX, MVX), and FDA drug labels.
+ * vaccine codes (CVX, MVX), FDA drug labels, SNOMED CT concepts, connectivity
+ * intelligence, and claims editing/payment data (NCCI, MUE, PFS, Coverage).
  *
  * @example
  * ```ts
- * import { Fhirfly } from "@fhirfly/sdk";
+ * import { Fhirfly } from "@fhirfly-io/terminology";
  *
  * // Option A: API key (simple)
  * const client = new Fhirfly({ apiKey: "ffly_sk_live_..." });
@@ -2022,7 +2382,7 @@ type FhirflyConfig = FhirflyApiKeyConfig | FhirflyOAuthConfig;
  *
  * // Look up a drug by NDC
  * const ndc = await client.ndc.lookup("0069-0151-01");
- * console.log(ndc.data.product_name); // "Lipitor"
+ * console.log(ndc.data.brand_name); // "Lipitor"
  * ```
  */
 declare class Fhirfly {
@@ -2069,6 +2429,11 @@ declare class Fhirfly {
      * Look up clinical concepts from the SNOMED CT IPS free set (~12K concepts, CC BY 4.0).
      */
     readonly snomed: SnomedEndpoint;
+    /**
+     * Claims Intelligence endpoints (requires `claims.read` scope).
+     * NCCI PTP validation, MUE limits, PFS/RVU fee schedule, LCD/NCD coverage.
+     */
+    readonly claims: ClaimsEndpoint;
     /**
      * Create a new FHIRfly client.
      *
@@ -2154,4 +2519,4 @@ declare class TimeoutError extends FhirflyError {
     constructor(timeoutMs: number);
 }
 
-export { type ActiveIngredient, ApiError, type ApiResponse, AuthenticationError, type AuthorizedOfficial, type BatchLookupOptions, type BatchResponse, type BatchResultItem, type ConnectivityEndpointData, type ConnectivityMeta, type ConnectivityTargetData, type CvxCompact, type CvxData, type CvxFull, type CvxSearchParams, type CvxStandard, type Deactivation, type DisplayField, type EndpointAuthRequirements, type EndpointAvailability, type EnrichedTaxonomy, type EvidenceSummary, type FdaLabelBundleName, type FdaLabelData, type FdaLabelLookupOptions, type FdaLabelMetadata, type FdaLabelSearchCompact, type FdaLabelSearchData, type FdaLabelSearchFull, type FdaLabelSearchParams, type FdaLabelSearchStandard, type FhirMetadata, Fhirfly, type FhirflyApiKeyConfig, type FhirflyConfig, FhirflyError, type FhirflyOAuthConfig, type Icd10Compact, type Icd10Data, type Icd10Full, type Icd10SearchParams, type Icd10Standard, type Icd10Type, type IncludeOption, type IpsCategory, type LegalInfo, type LoincCompact, type LoincData, type LoincFhirCoding, type LoincFull, type LoincParts, type LoincRanks, type LoincSearchParams, type LoincSourceOrg, type LoincStandard, type LoincUnits, type LookupOptions, type MvxCompact, type MvxData, type MvxFhirCoding, type MvxFull, type MvxIngest, type MvxSearchParams, type MvxStandard, type NdcCompact, type NdcData, type NdcFull, type NdcSearchParams, type NdcStandard, type NdcType, NetworkError, NotFoundError, type NpiAddress, type NpiCompact, type NpiConnectivityData, type NpiData, type NpiFull, type NpiSearchParams, type NpiStandard, type OtherIdentifier, type PersonName, type ProviderSummary, QuotaExceededError, RateLimitError, type ResponseMeta, type ResponseShape, type RxNormCompact, type RxNormData, type RxNormFull, type RxNormSearchParams, type RxNormStandard, type RxTermType, type SearchFacets, type SearchLegalInfo, type SearchOptions, type SearchResponse, type SecondaryLocation, ServerError, type SnomedBatchResultItem, type SnomedCategoriesResponse, type SnomedConcept, type SnomedEnrichmentFull, type SnomedEnrichmentStandard, type SnomedMappingSource, type SnomedMappingSourceSystem, type SnomedMappingType, type SnomedReverseMapping, type SnomedReverseMappingData, type SnomedSearchParams, TimeoutError, TokenManager, ValidationError };
+export { type ActiveIngredient, ApiError, type ApiResponse, AuthenticationError, type AuthorizedOfficial, type BatchLookupOptions, type BatchResponse, type BatchResultItem, type ClaimsLegalInfo, type ClaimsMeta, type ConnectivityEndpointData, type ConnectivityMeta, type ConnectivityTargetData, type CoverageCheckData, type CoverageCheckItem, type CoverageCheckResponse, type CoveragePolicyType, type CvxCompact, type CvxData, type CvxFull, type CvxSearchParams, type CvxStandard, type Deactivation, type DisplayField, type EndpointAuthRequirements, type EndpointAvailability, type EnrichedTaxonomy, type EvidenceSummary, type FdaLabelBundleName, type FdaLabelData, type FdaLabelLookupOptions, type FdaLabelMetadata, type FdaLabelSearchCompact, type FdaLabelSearchData, type FdaLabelSearchFull, type FdaLabelSearchParams, type FdaLabelSearchStandard, type FhirMetadata, Fhirfly, type FhirflyApiKeyConfig, type FhirflyConfig, FhirflyError, type FhirflyOAuthConfig, type Icd10Compact, type Icd10Data, type Icd10Full, type Icd10SearchParams, type Icd10Standard, type Icd10Type, type IncludeOption, type IpsCategory, type LegalInfo, type LoincCompact, type LoincData, type LoincFhirCoding, type LoincFull, type LoincParts, type LoincRanks, type LoincSearchParams, type LoincSourceOrg, type LoincStandard, type LoincUnits, type LookupOptions, type MueBatchResponse, type MueBatchResultItem, type MueLimitItem, type MueLookupData, type MueLookupResponse, type MueServiceType, type MvxCompact, type MvxData, type MvxFhirCoding, type MvxFull, type MvxIngest, type MvxSearchParams, type MvxStandard, type NcciClaimType, type NcciEditItem, type NcciValidateData, type NcciValidateResponse, type NdcCompact, type NdcData, type NdcFull, type NdcSearchParams, type NdcStandard, type NdcType, NetworkError, NotFoundError, type NpiAddress, type NpiCompact, type NpiConnectivityData, type NpiData, type NpiFull, type NpiSearchParams, type NpiStandard, type OtherIdentifier, type PersonName, type PfsBatchResponse, type PfsBatchResultItem, type PfsIndicators, type PfsLookupData, type PfsLookupResponse, type PfsPayment, type PfsRvu, type ProviderSummary, QuotaExceededError, RateLimitError, type ResponseMeta, type ResponseShape, type RxNormCompact, type RxNormData, type RxNormFull, type RxNormSearchParams, type RxNormStandard, type RxTermType, type SearchFacets, type SearchLegalInfo, type SearchOptions, type SearchResponse, type SecondaryLocation, ServerError, type SnomedBatchResultItem, type SnomedCategoriesResponse, type SnomedConcept, type SnomedEnrichmentFull, type SnomedEnrichmentStandard, type SnomedMappingSource, type SnomedMappingSourceSystem, type SnomedMappingType, type SnomedReverseMapping, type SnomedReverseMappingData, type SnomedSearchParams, TimeoutError, TokenManager, ValidationError };