@fhirfly-io/terminology 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -71,6 +71,55 @@ interface BatchResponse<T> {
 interface DisplayField {
     display?: string;
 }
+/**
+ * Common options for all search methods.
+ */
+interface SearchOptions {
+    /** Response detail level. Default: "compact" */
+    shape?: ResponseShape;
+    /** Include additional fields like pre-formatted display strings */
+    include?: IncludeOption[];
+    /** Results per page (1-100). Default: 20 */
+    limit?: number;
+    /** Page number (1-100). Default: 1 */
+    page?: number;
+}
+/**
+ * Facet counts in search results.
+ */
+type SearchFacets = Record<string, Record<string, number>>;
+/**
+ * Legal metadata for search results.
+ */
+interface SearchLegalInfo {
+    license: string;
+    source_name: string;
+    citation: string;
+    attribution_required: boolean;
+}
+/**
+ * Search response wrapper.
+ */
+interface SearchResponse<T> {
+    /** Search result items */
+    items: T[];
+    /** Total number of matching results */
+    total: number;
+    /** Whether total was capped (e.g., at 10,000) */
+    total_capped: boolean;
+    /** Whether there are more results */
+    has_more: boolean;
+    /** Current page number */
+    page: number;
+    /** Results per page */
+    limit: number;
+    /** Facet counts for filtering */
+    facets: SearchFacets;
+    /** Legal and attribution metadata */
+    meta: {
+        legal: SearchLegalInfo;
+    };
+}
 
 /**
  * OAuth2 client credentials configuration.
@@ -132,6 +181,10 @@ declare class HttpClient {
      * Build query string from options.
      */
     private buildQueryString;
+    /**
+     * Build query string from search params object.
+     */
+    buildSearchQueryString(params: Record<string, unknown>): string;
     /**
      * Parse error response from API.
      */
@@ -156,6 +209,10 @@ declare class HttpClient {
      * Make a POST request.
      */
     post<T>(endpoint: string, body: unknown, options?: LookupOptions): Promise<T>;
+    /**
+     * Make a GET request with search parameters.
+     */
+    search<T>(endpoint: string, params: Record<string, unknown>): Promise<T>;
 }
 
 /**
@@ -210,6 +267,45 @@ interface NdcFull extends NdcStandard {
  * NDC response type based on shape.
  */
 type NdcData = NdcCompact | NdcStandard | NdcFull;
+/**
+ * NDC search parameters.
+ */
+interface NdcSearchParams {
+    /** General text search across product names */
+    q?: string;
+    /** Search by product name */
+    name?: string;
+    /** Search by brand name */
+    brand?: string;
+    /** Search by generic name */
+    generic?: string;
+    /** Search by active ingredient */
+    ingredient?: string;
+    /** Filter by strength (e.g., "200mg", "10mg/5ml") */
+    strength?: string;
+    /** Filter by dosage form (e.g., "TABLET", "CAPSULE") */
+    dosage_form?: string;
+    /** Filter by administration route */
+    route?: string;
+    /** Filter by labeler/manufacturer name */
+    labeler?: string;
+    /** Filter by product type: "otc", "rx", or "all" */
+    product_type?: "otc" | "rx" | "all";
+    /** Filter by DEA schedule: "ci", "cii", "ciii", "civ", "cv", "none" */
+    dea_schedule?: "ci" | "cii" | "ciii" | "civ" | "cv" | "none";
+    /** Filter by marketing category */
+    marketing_category?: string;
+    /** Filter by pharmacologic class */
+    pharm_class?: string;
+    /** Filter by active status */
+    is_active?: boolean;
+    /** Filter by RxNorm linkage */
+    has_rxcui?: boolean;
+    /** Filter by specific RxNorm CUI */
+    rxcui?: string;
+    /** Sort order: "relevance", "name", "labeler" */
+    sort?: "relevance" | "name" | "labeler";
+}
 
 /**
  * NDC (National Drug Code) API endpoint.
@@ -256,6 +352,32 @@ declare class NdcEndpoint {
      * ```
      */
     lookupMany(codes: string[], options?: BatchLookupOptions): Promise<BatchResponse<NdcData>>;
+    /**
+     * Search for NDC products.
+     *
+     * @param params - Search parameters (q, name, brand, ingredient, etc.)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search by drug name
+     * const results = await client.ndc.search({ q: "advil" });
+     *
+     * // Search with filters
+     * const results = await client.ndc.search({
+     *   ingredient: "ibuprofen",
+     *   dosage_form: "TABLET",
+     *   product_type: "otc"
+     * });
+     *
+     * console.log(`Found ${results.total} products`);
+     * for (const item of results.items) {
+     *   console.log(item.product_name);
+     * }
+     * ```
+     */
+    search(params: NdcSearchParams, options?: SearchOptions): Promise<SearchResponse<NdcData>>;
 }
 
 /**
@@ -335,6 +457,39 @@ interface NpiFull extends NpiStandard {
  * NPI response type based on shape.
  */
 type NpiData = NpiCompact | NpiStandard | NpiFull;
+/**
+ * NPI search parameters.
+ */
+interface NpiSearchParams {
+    /** General text search */
+    q?: string;
+    /** Search by provider name */
+    name?: string;
+    /** Filter by first name (individuals only) */
+    first_name?: string;
+    /** Filter by last name (individuals only) */
+    last_name?: string;
+    /** Search by organization name */
+    organization?: string;
+    /** Filter by taxonomy code */
+    taxonomy?: string;
+    /** Search by specialty description */
+    specialty?: string;
+    /** Filter by state (2-letter code) */
+    state?: string;
+    /** Filter by city */
+    city?: string;
+    /** Filter by postal code */
+    postal_code?: string;
+    /** Filter by phone number */
+    phone?: string;
+    /** Filter by entity type */
+    entity_type?: "individual" | "organization";
+    /** Filter by active status */
+    active?: boolean;
+    /** Sort order: "relevance", "name", "location" */
+    sort?: "relevance" | "name" | "location";
+}
 
 /**
  * NPI (National Provider Identifier) API endpoint.
@@ -372,6 +527,29 @@ declare class NpiEndpoint {
      * ```
      */
     lookupMany(npis: string[], options?: BatchLookupOptions): Promise<BatchResponse<NpiData>>;
+    /**
+     * Search for healthcare providers.
+     *
+     * @param params - Search parameters (q, name, specialty, state, etc.)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search by name
+     * const results = await client.npi.search({ q: "smith" });
+     *
+     * // Search with filters
+     * const results = await client.npi.search({
+     *   specialty: "cardiology",
+     *   state: "CA",
+     *   entity_type: "individual"
+     * });
+     *
+     * console.log(`Found ${results.total} providers`);
+     * ```
+     */
+    search(params: NpiSearchParams, options?: SearchOptions): Promise<SearchResponse<NpiData>>;
 }
 
 /**
@@ -423,6 +601,33 @@ interface RxNormFull extends RxNormStandard {
  * RxNorm response type based on shape.
  */
 type RxNormData = RxNormCompact | RxNormStandard | RxNormFull;
+/**
+ * RxNorm search parameters.
+ */
+interface RxNormSearchParams {
+    /** General text search */
+    q?: string;
+    /** Search by drug name */
+    name?: string;
+    /** Search by ingredient name */
+    ingredient?: string;
+    /** Search by brand name */
+    brand?: string;
+    /** Filter by term type(s), comma-separated (e.g., "SCD,SBD") */
+    tty?: string;
+    /** Filter by prescribable status */
+    is_prescribable?: boolean;
+    /** Filter by status: "active", "removed", "remapped", "obsolete" */
+    status?: string;
+    /** Filter by semantic type */
+    semantic_type?: string;
+    /** Filter by NDC linkage */
+    has_ndc?: boolean;
+    /** Filter by specific NDC */
+    ndc?: string;
+    /** Sort order: "relevance", "name" */
+    sort?: "relevance" | "name";
+}
 
 /**
  * RxNorm API endpoint.
@@ -452,6 +657,26 @@ declare class RxNormEndpoint {
      * @returns Batch response with results for each RxCUI
      */
     lookupMany(rxcuis: string[], options?: BatchLookupOptions): Promise<BatchResponse<RxNormData>>;
+    /**
+     * Search for drugs in RxNorm.
+     *
+     * @param params - Search parameters (q, name, ingredient, brand, etc.)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search by drug name
+     * const results = await client.rxnorm.search({ q: "lipitor" });
+     *
+     * // Search prescribable drugs by ingredient
+     * const results = await client.rxnorm.search({
+     *   ingredient: "metformin",
+     *   is_prescribable: true
+     * });
+     * ```
+     */
+    search(params: RxNormSearchParams, options?: SearchOptions): Promise<SearchResponse<RxNormData>>;
 }
 
 /**
@@ -508,6 +733,31 @@ interface LoincFull extends LoincStandard {
  * LOINC response type based on shape.
  */
 type LoincData = LoincCompact | LoincStandard | LoincFull;
+/**
+ * LOINC search parameters.
+ */
+interface LoincSearchParams {
+    /** General text search */
+    q?: string;
+    /** Search by component name */
+    component?: string;
+    /** Filter by LOINC class (e.g., "CHEM", "HEM/BC") */
+    class?: string;
+    /** Filter by specimen/system type (e.g., "Bld", "Ser", "Urine") */
+    system?: string;
+    /** Filter by property */
+    property?: string;
+    /** Filter by scale type: "Qn", "Ord", "Nom", "Nar", etc. */
+    scale?: string;
+    /** Filter by method */
+    method?: string;
+    /** Filter by order/observation type: "Order", "Observation", "Both" */
+    order_obs?: string;
+    /** Filter by status: "ACTIVE", "DEPRECATED", "DISCOURAGED", etc. */
+    status?: string;
+    /** Sort order: "relevance", "name", "code" */
+    sort?: "relevance" | "name" | "code";
+}
 
 /**
  * LOINC API endpoint.
@@ -537,6 +787,27 @@ declare class LoincEndpoint {
      * @returns Batch response with results for each LOINC
      */
     lookupMany(loincNums: string[], options?: BatchLookupOptions): Promise<BatchResponse<LoincData>>;
+    /**
+     * Search for LOINC codes.
+     *
+     * @param params - Search parameters (q, component, class, system, etc.)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search by term
+     * const results = await client.loinc.search({ q: "glucose" });
+     *
+     * // Search blood chemistry tests
+     * const results = await client.loinc.search({
+     *   class: "CHEM",
+     *   system: "Bld",
+     *   scale: "Qn"
+     * });
+     * ```
+     */
+    search(params: LoincSearchParams, options?: SearchOptions): Promise<SearchResponse<LoincData>>;
 }
 
 /**
@@ -589,6 +860,33 @@ interface Icd10Full extends Icd10Standard {
  * ICD-10 response type based on shape.
  */
 type Icd10Data = Icd10Compact | Icd10Standard | Icd10Full;
+/**
+ * ICD-10 search parameters.
+ */
+interface Icd10SearchParams {
+    /** General text search */
+    q?: string;
+    /** Filter by code system: "CM" (diagnosis) or "PCS" (procedure) */
+    code_system?: "CM" | "PCS";
+    /** Filter by chapter (CM only) */
+    chapter?: string;
+    /** Filter by block (CM only) */
+    block?: string;
+    /** Filter by billable codes only */
+    billable?: boolean;
+    /** Filter by section (PCS only) */
+    section?: string;
+    /** Filter by body system (PCS only) */
+    body_system?: string;
+    /** Filter by root operation (PCS only) */
+    root_operation?: string;
+    /** Filter by approach (PCS only) */
+    approach?: string;
+    /** Filter by status */
+    status?: string;
+    /** Sort order: "relevance", "code", "display" */
+    sort?: "relevance" | "code" | "display";
+}
 
 /**
  * ICD-10 API endpoint.
@@ -640,6 +938,30 @@ declare class Icd10Endpoint {
      * @returns Batch response with results for each code
      */
     lookupPcsMany(codes: string[], options?: BatchLookupOptions): Promise<BatchResponse<Icd10Data>>;
+    /**
+     * Search for ICD-10 codes (both CM and PCS).
+     *
+     * @param params - Search parameters (q, code_system, chapter, billable, etc.)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search diagnosis codes
+     * const results = await client.icd10.search({
+     *   q: "diabetes",
+     *   code_system: "CM",
+     *   billable: true
+     * });
+     *
+     * // Search procedure codes
+     * const results = await client.icd10.search({
+     *   q: "bypass",
+     *   code_system: "PCS"
+     * });
+     * ```
+     */
+    search(params: Icd10SearchParams, options?: SearchOptions): Promise<SearchResponse<Icd10Data>>;
 }
 
 /**
@@ -671,6 +993,21 @@ interface CvxFull extends CvxStandard {
  * CVX response type based on shape.
  */
 type CvxData = CvxCompact | CvxStandard | CvxFull;
+/**
+ * CVX search parameters.
+ */
+interface CvxSearchParams {
+    /** General text search */
+    q?: string;
+    /** Filter by status: "active", "inactive" */
+    status?: string;
+    /** Filter by vaccine type (e.g., "mRNA", "live", "inactivated") */
+    vaccine_type?: string;
+    /** Filter for COVID-19 vaccines only */
+    is_covid_vaccine?: boolean;
+    /** Sort order: "relevance", "name", "code" */
+    sort?: "relevance" | "name" | "code";
+}
 
 /**
  * CVX (Vaccine Codes) API endpoint.
@@ -700,6 +1037,26 @@ declare class CvxEndpoint {
      * @returns Batch response with results for each code
      */
     lookupMany(cvxCodes: string[], options?: BatchLookupOptions): Promise<BatchResponse<CvxData>>;
+    /**
+     * Search for vaccine codes.
+     *
+     * @param params - Search parameters (q, status, vaccine_type, is_covid_vaccine)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search for flu vaccines
+     * const results = await client.cvx.search({ q: "influenza" });
+     *
+     * // Find all COVID-19 vaccines
+     * const results = await client.cvx.search({
+     *   is_covid_vaccine: true,
+     *   status: "active"
+     * });
+     * ```
+     */
+    search(params: CvxSearchParams, options?: SearchOptions): Promise<SearchResponse<CvxData>>;
 }
 
 /**
@@ -730,6 +1087,17 @@ interface MvxFull extends MvxStandard {
  * MVX response type based on shape.
  */
 type MvxData = MvxCompact | MvxStandard | MvxFull;
+/**
+ * MVX search parameters.
+ */
+interface MvxSearchParams {
+    /** General text search */
+    q?: string;
+    /** Filter by status: "active", "inactive" */
+    status?: string;
+    /** Sort order: "relevance", "name", "code" */
+    sort?: "relevance" | "name" | "code";
+}
 
 /**
  * MVX (Vaccine Manufacturer Codes) API endpoint.
@@ -759,6 +1127,23 @@ declare class MvxEndpoint {
      * @returns Batch response with results for each code
      */
     lookupMany(mvxCodes: string[], options?: BatchLookupOptions): Promise<BatchResponse<MvxData>>;
+    /**
+     * Search for vaccine manufacturers.
+     *
+     * @param params - Search parameters (q, status)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search by name
+     * const results = await client.mvx.search({ q: "pfizer" });
+     *
+     * // List all active manufacturers
+     * const results = await client.mvx.search({ status: "active" });
+     * ```
+     */
+    search(params: MvxSearchParams, options?: SearchOptions): Promise<SearchResponse<MvxData>>;
 }
 
 /**
@@ -809,6 +1194,41 @@ interface FdaLabelFull extends FdaLabelStandard {
  * FDA Label response type based on shape.
  */
 type FdaLabelData = FdaLabelCompact | FdaLabelStandard | FdaLabelFull;
+/**
+ * FDA Label search parameters.
+ */
+interface FdaLabelSearchParams {
+    /** General text search */
+    q?: string;
+    /** Search by product name */
+    name?: string;
+    /** Search by brand name */
+    brand?: string;
+    /** Search by generic name */
+    generic?: string;
+    /** Search by active substance/ingredient */
+    substance?: string;
+    /** Search by manufacturer name */
+    manufacturer?: string;
+    /** Filter by product type: "otc", "rx", "cellular" */
+    product_type?: "otc" | "rx" | "cellular";
+    /** Filter by administration route */
+    route?: string;
+    /** Filter by pharmacologic class */
+    pharm_class?: string;
+    /** Filter by RxNorm linkage */
+    has_rxcui?: boolean;
+    /** Filter by specific RxCUI */
+    rxcui?: string;
+    /** Filter by specific NDC */
+    ndc?: string;
+    /** Filter by FDA application number */
+    application_number?: string;
+    /** Filter for current labels only (default: true) */
+    is_current?: boolean;
+    /** Sort order: "relevance", "name", "manufacturer" */
+    sort?: "relevance" | "name" | "manufacturer";
+}
 
 /**
  * FDA Labels API endpoint.
@@ -852,6 +1272,32 @@ declare class FdaLabelsEndpoint {
      * @returns Batch response with results for each Set ID
      */
     lookupMany(setIds: string[], options?: BatchLookupOptions): Promise<BatchResponse<FdaLabelData>>;
+    /**
+     * Search for FDA drug labels.
+     *
+     * @param params - Search parameters (q, name, brand, substance, manufacturer, etc.)
+     * @param options - Pagination and response shape options
+     * @returns Search results with facets
+     *
+     * @example
+     * ```ts
+     * // Search by drug name
+     * const results = await client.fdaLabels.search({ q: "advil" });
+     *
+     * // Search OTC pain relievers
+     * const results = await client.fdaLabels.search({
+     *   substance: "acetaminophen",
+     *   product_type: "otc"
+     * });
+     *
+     * // Search by manufacturer
+     * const results = await client.fdaLabels.search({
+     *   manufacturer: "pfizer",
+     *   product_type: "rx"
+     * });
+     * ```
+     */
+    search(params: FdaLabelSearchParams, options?: SearchOptions): Promise<SearchResponse<FdaLabelData>>;
 }
 
 /**
@@ -1065,4 +1511,4 @@ declare class TimeoutError extends FhirflyError {
     constructor(timeoutMs: number);
 }
 
-export { type ActiveIngredient, ApiError, type ApiResponse, AuthenticationError, type BatchLookupOptions, type BatchResponse, type BatchResultItem, type CvxCompact, type CvxData, type CvxFull, type CvxStandard, type DisplayField, type FdaLabelCompact, type FdaLabelData, type FdaLabelFull, type FdaLabelStandard, Fhirfly, type FhirflyApiKeyConfig, type FhirflyConfig, FhirflyError, type FhirflyOAuthConfig, type Icd10Compact, type Icd10Data, type Icd10Full, type Icd10Standard, type Icd10Type, type IncludeOption, type LegalInfo, type LoincCompact, type LoincData, type LoincFull, type LoincStandard, type LookupOptions, type MvxCompact, type MvxData, type MvxFull, type MvxStandard, type NdcCompact, type NdcData, type NdcFull, type NdcPackaging, type NdcStandard, NetworkError, NotFoundError, type NpiAddress, type NpiCompact, type NpiData, type NpiFull, type NpiIdentifier, type NpiStandard, type NpiTaxonomy, QuotaExceededError, RateLimitError, type ResponseMeta, type ResponseShape, type RxNormCompact, type RxNormData, type RxNormFull, type RxNormStandard, type RxTermType, ServerError, TimeoutError, TokenManager, ValidationError };
+export { type ActiveIngredient, ApiError, type ApiResponse, AuthenticationError, type BatchLookupOptions, type BatchResponse, type BatchResultItem, type CvxCompact, type CvxData, type CvxFull, type CvxSearchParams, type CvxStandard, type DisplayField, type FdaLabelCompact, type FdaLabelData, type FdaLabelFull, type FdaLabelSearchParams, type FdaLabelStandard, Fhirfly, type FhirflyApiKeyConfig, type FhirflyConfig, FhirflyError, type FhirflyOAuthConfig, type Icd10Compact, type Icd10Data, type Icd10Full, type Icd10SearchParams, type Icd10Standard, type Icd10Type, type IncludeOption, type LegalInfo, type LoincCompact, type LoincData, type LoincFull, type LoincSearchParams, type LoincStandard, type LookupOptions, type MvxCompact, type MvxData, type MvxFull, type MvxSearchParams, type MvxStandard, type NdcCompact, type NdcData, type NdcFull, type NdcPackaging, type NdcSearchParams, type NdcStandard, NetworkError, NotFoundError, type NpiAddress, type NpiCompact, type NpiData, type NpiFull, type NpiIdentifier, type NpiSearchParams, type NpiStandard, type NpiTaxonomy, 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, ServerError, TimeoutError, TokenManager, ValidationError };