@fhirfly-io/terminology 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -27,6 +27,28 @@ interface LegalInfo {
     attribution?: string;
     source_url?: string;
 }
+/**
+ * Provenance information included in full-shape responses.
+ * Describes the upstream data source, version, and when FHIRfly last ingested it.
+ */
+interface SourceInfo {
+    /** Name of the data source (e.g., "FDA NDC Directory", "CMS NPPES") */
+    name: string;
+    /** URL of the authoritative source */
+    url?: string;
+    /** Version or release identifier of the source data */
+    version?: string;
+    /** ISO 8601 timestamp of when FHIRfly last ingested this data */
+    fhirfly_updated_at?: string;
+    /** Version of the FHIRfly ETL pipeline that processed this data */
+    fhirfly_etl_version?: string;
+    /** Component data sources (used when a dataset combines multiple sources, e.g., NPI = NPPES + NUCC) */
+    components?: Array<{
+        name: string;
+        version: string;
+        url?: string;
+    }>;
+}
 /**
  * Metadata included in all API responses.
  */
@@ -66,6 +88,8 @@ interface BatchResponse<T> {
     /** Response metadata */
     meta: {
         legal: LegalInfo;
+        /** Provenance information. Included when shape=full. */
+        source?: SourceInfo;
     };
 }
 /**
@@ -1090,11 +1114,17 @@ interface Icd10Standard extends Icd10Compact {
     root_operation?: string;
     /** SNOMED CT mappings (ICD-10-CM only, added by enrichment) */
     snomed?: SnomedEnrichmentStandard[];
+    /** HCC crosswalk mappings (ICD-10-CM only, added by enrichment) */
+    hcc?: Array<{
+        cc_number: number;
+        model_version: string;
+        model_type: string;
+    }>;
 }
 /**
  * ICD-10 lookup result - full shape.
  */
-interface Icd10Full extends Omit<Icd10Standard, "snomed"> {
+interface Icd10Full extends Omit<Icd10Standard, "snomed" | "hcc"> {
     /** ICD-10-CM specific */
     includes?: string[];
     excludes1?: string[];
@@ -1110,6 +1140,14 @@ interface Icd10Full extends Omit<Icd10Standard, "snomed"> {
     end_date?: string;
     /** SNOMED CT mappings with FHIR coding (ICD-10-CM only, added by enrichment) */
     snomed?: SnomedEnrichmentFull[];
+    /** HCC crosswalk mappings with payment details (ICD-10-CM only, added by enrichment) */
+    hcc?: Array<{
+        cc_number: number;
+        model_version: string;
+        model_type: string;
+        payment_year: string;
+        release_type: string;
+    }>;
 }
 /**
  * ICD-10 response type based on shape.
@@ -2530,6 +2568,302 @@ declare class SmaEndpoint {
     stats(): Promise<SmaStatsResponse>;
 }
 
+/**
+ * FHIR coding representation for HCC.
+ */
+interface HccFhirCoding {
+    system: string;
+    code: string;
+    display?: string;
+}
+/**
+ * ETL ingest tracking metadata for HCC.
+ */
+interface HccIngest {
+    source: string;
+    file_tag: string;
+    etl_version: string;
+    run_id: string;
+    first_seen: string;
+    last_seen: string;
+    is_current: boolean;
+}
+/**
+ * HCC crosswalk lookup result - compact shape.
+ * Minimal data for lists, autocomplete.
+ */
+interface HccCompact {
+    icd10_code: string;
+    cc_number: number;
+    model_version: string;
+    model_type: string;
+}
+/**
+ * HCC crosswalk lookup result - standard shape.
+ * Core structured data for most API integrations.
+ */
+interface HccStandard extends HccCompact {
+    payment_year: string;
+    release_type: string;
+    mapping_source: string;
+    fhir_coding: HccFhirCoding;
+}
+/**
+ * HCC crosswalk lookup result - full shape.
+ * Complete data with provenance for AI agents.
+ */
+interface HccFull extends HccStandard {
+    ingest: HccIngest;
+}
+/**
+ * HCC response type based on shape.
+ */
+type HccData = HccCompact | HccStandard | HccFull;
+/**
+ * HCC reverse lookup result.
+ * Returns ICD-10 codes that map to a given HCC category.
+ */
+interface HccReverseResult {
+    cc_number: number;
+    model_version: string;
+    model_type: string;
+    icd10_codes: string[];
+}
+/**
+ * HCC search parameters.
+ */
+interface HccSearchParams {
+    /** General text search */
+    q?: string;
+    /** Filter by model version (e.g., "V28", "V24") */
+    model_version?: string;
+    /** Filter by model type (e.g., "CMS-HCC", "RxHCC") */
+    model_type?: string;
+    /** Filter by condition category number */
+    cc_number?: number;
+    /** Filter by payment year */
+    payment_year?: string;
+    /** Sort order: "relevance", "cc_number", "icd10_code" */
+    sort?: "relevance" | "cc_number" | "icd10_code";
+}
+
+/**
+ * Options for HCC reverse lookups.
+ */
+interface HccReverseLookupOptions extends LookupOptions {
+    /** Filter by HCC model (e.g., "CMS-HCC", "RxHCC") */
+    model?: string;
+}
+/**
+ * HCC (Hierarchical Condition Categories) API endpoint.
+ *
+ * Provides access to HCC crosswalk data mapping ICD-10 diagnosis codes
+ * to CMS risk adjustment condition categories.
+ */
+declare class HccEndpoint {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Look up HCC mappings for a single ICD-10 code.
+     *
+     * Returns all HCC category mappings for the given diagnosis code.
+     *
+     * @param icd10Code - ICD-10-CM diagnosis code (e.g., "E11.9")
+     * @param options - Response shape and include options
+     * @returns HCC mapping data (may contain multiple mappings)
+     *
+     * @example
+     * ```ts
+     * const result = await client.hcc.lookup("E11.9");
+     * console.log(result.data); // HCC mapping(s) for Type 2 diabetes
+     * ```
+     */
+    lookup(icd10Code: string, options?: LookupOptions): Promise<ApiResponse<HccData[]>>;
+    /**
+     * Look up HCC mappings for multiple ICD-10 codes in a single request.
+     *
+     * @param codes - Array of ICD-10-CM codes (max 100)
+     * @param options - Response shape, include, and batch options
+     * @returns Batch response with HCC mappings for each code
+     */
+    lookupMany(codes: string[], options?: BatchLookupOptions): Promise<BatchResponse<HccData[]>>;
+    /**
+     * Reverse lookup: find ICD-10 codes that map to a given HCC category.
+     *
+     * @param ccNumber - HCC condition category number
+     * @param options - Response shape, include, and model filter options
+     * @returns Reverse lookup result with array of ICD-10 codes
+     *
+     * @example
+     * ```ts
+     * // Find all ICD-10 codes that map to HCC 19 (Diabetes)
+     * const result = await client.hcc.reverse(19);
+     * console.log(result.data.icd10_codes);
+     *
+     * // Filter by model
+     * const result = await client.hcc.reverse(19, { model: "CMS-HCC" });
+     * ```
+     */
+    reverse(ccNumber: number, options?: HccReverseLookupOptions): Promise<ApiResponse<HccReverseResult>>;
+    /**
+     * Search for HCC crosswalk mappings.
+     *
+     * @param params - Search parameters (q, model_version, model_type, cc_number, payment_year)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search by ICD-10 code text
+     * const results = await client.hcc.search({ q: "diabetes" });
+     *
+     * // Filter by model version
+     * const results = await client.hcc.search({
+     *   model_version: "V28",
+     *   cc_number: 19
+     * });
+     * ```
+     */
+    search(params: HccSearchParams, options?: SearchOptions): Promise<SearchResponse<HccData>>;
+}
+
+/**
+ * FHIR coding representation for OPCS-4.
+ */
+interface Opcs4FhirCoding {
+    system: string;
+    code: string;
+    display?: string;
+}
+/**
+ * OPCS-4 structural hierarchy information.
+ */
+interface Opcs4Structure {
+    chapter: {
+        code: string;
+        title: string;
+    };
+    category: string;
+}
+/**
+ * Legal/licensing information for OPCS-4.
+ */
+interface Opcs4Legal {
+    license: string;
+    copyright: string;
+    attribution: string;
+}
+/**
+ * ETL ingest tracking metadata for OPCS-4.
+ */
+interface Opcs4Ingest {
+    source: string;
+    file_tag: string;
+    etl_version: string;
+    run_id: string;
+    first_seen: string;
+    last_seen: string;
+    is_current: boolean;
+}
+/**
+ * OPCS-4 procedure code lookup result - compact shape.
+ * Minimal data for lists, autocomplete.
+ */
+interface Opcs4Compact extends DisplayField {
+    code: string;
+    code_system: "OPCS-4";
+    display: string;
+}
+/**
+ * OPCS-4 procedure code lookup result - standard shape.
+ * Core structured data for most API integrations.
+ */
+interface Opcs4Standard extends Opcs4Compact {
+    system: string;
+    version: string;
+    structure: Opcs4Structure;
+    fhir_coding: Opcs4FhirCoding;
+    effective_date: string;
+}
+/**
+ * OPCS-4 procedure code lookup result - full shape.
+ * Complete data with provenance for AI agents.
+ */
+interface Opcs4Full extends Opcs4Standard {
+    legal: Opcs4Legal;
+    ingest: Opcs4Ingest;
+}
+/**
+ * OPCS-4 response type based on shape.
+ */
+type Opcs4Data = Opcs4Compact | Opcs4Standard | Opcs4Full;
+/**
+ * OPCS-4 search parameters.
+ */
+interface Opcs4SearchParams {
+    /** General text search */
+    q?: string;
+    /** Filter by chapter code */
+    chapter?: string;
+    /** Filter by category */
+    category?: string;
+    /** Sort order: "relevance", "code", "display" */
+    sort?: "relevance" | "code" | "display";
+}
+
+/**
+ * OPCS-4 (Office of Population Censuses and Surveys Classification of
+ * Interventions and Procedures) API endpoint.
+ *
+ * Provides access to the UK's procedural coding system used by the NHS.
+ */
+declare class Opcs4Endpoint {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Look up a single OPCS-4 procedure code.
+     *
+     * @param code - OPCS-4 procedure code (e.g., "W37.1")
+     * @param options - Response shape and include options
+     * @returns OPCS-4 data
+     *
+     * @example
+     * ```ts
+     * const result = await client.opcs4.lookup("W37.1");
+     * console.log(result.data.display); // Procedure description
+     * ```
+     */
+    lookup(code: string, options?: LookupOptions): Promise<ApiResponse<Opcs4Data>>;
+    /**
+     * Look up multiple OPCS-4 codes in a single request.
+     *
+     * @param codes - Array of OPCS-4 codes (max 100)
+     * @param options - Response shape, include, and batch options
+     * @returns Batch response with results for each code
+     */
+    lookupMany(codes: string[], options?: BatchLookupOptions): Promise<BatchResponse<Opcs4Data>>;
+    /**
+     * Search for OPCS-4 procedure codes.
+     *
+     * @param params - Search parameters (q, chapter, category)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search for knee procedures
+     * const results = await client.opcs4.search({ q: "knee replacement" });
+     *
+     * // Filter by chapter
+     * const results = await client.opcs4.search({
+     *   chapter: "W",
+     *   q: "joint"
+     * });
+     * ```
+     */
+    search(params: Opcs4SearchParams, options?: SearchOptions): Promise<SearchResponse<Opcs4Data>>;
+}
+
 /**
  * Base configuration options shared by all auth modes.
  */
@@ -2677,6 +3011,16 @@ declare class Fhirfly {
      * State FHIR endpoint implementation status, patient access, and provider directories.
      */
     readonly sma: SmaEndpoint;
+    /**
+     * HCC (Hierarchical Condition Categories) crosswalk lookups.
+     * Map ICD-10 diagnosis codes to CMS risk adjustment categories.
+     */
+    readonly hcc: HccEndpoint;
+    /**
+     * OPCS-4 (Office of Population Censuses and Surveys) procedure code lookups.
+     * UK NHS procedural coding system.
+     */
+    readonly opcs4: Opcs4Endpoint;
     /**
      * Create a new FHIRfly client.
      *
@@ -2762,4 +3106,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 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 SmaListOptions, type SmaMetaResponse, type SmaStateDetailResponse, type SmaStateSummary, type SmaStatesListResponse, type SmaStatsResponse, 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 HccCompact, type HccData, HccEndpoint, type HccFhirCoding, type HccFull, type HccIngest, type HccReverseLookupOptions, type HccReverseResult, type HccSearchParams, type HccStandard, 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 Opcs4Compact, type Opcs4Data, Opcs4Endpoint, type Opcs4FhirCoding, type Opcs4Full, type Opcs4Ingest, type Opcs4Legal, type Opcs4SearchParams, type Opcs4Standard, type Opcs4Structure, 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 SmaListOptions, type SmaMetaResponse, type SmaStateDetailResponse, type SmaStateSummary, type SmaStatesListResponse, type SmaStatsResponse, 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 };