@medplum/core 5.1.13 → 5.1.14

package/dist/cjs/index.d.ts

@@ -26,6 +26,8 @@ import type { HumanName } from '@medplum/fhirtypes';
 import type { Identifier } from '@medplum/fhirtypes';
 import type { ImagingStudy } from '@medplum/fhirtypes';
 import type { Media } from '@medplum/fhirtypes';
+import type { Medication } from '@medplum/fhirtypes';
+import type { MedicationRequest } from '@medplum/fhirtypes';
 import type { Meta } from '@medplum/fhirtypes';
 import type { Money } from '@medplum/fhirtypes';
 import type { Observation } from '@medplum/fhirtypes';
@@ -35,6 +37,7 @@ import type { ObservationDefinitionQualifiedInterval } from '@medplum/fhirtypes'
 import type { OperationOutcome } from '@medplum/fhirtypes';
 import type { OperationOutcomeIssue } from '@medplum/fhirtypes';
 import type { Organization } from '@medplum/fhirtypes';
+import type { Parameters as Parameters_2 } from '@medplum/fhirtypes';
 import type { Patient } from '@medplum/fhirtypes';
 import type { Period } from '@medplum/fhirtypes';
 import type { Practitioner } from '@medplum/fhirtypes';
@@ -492,6 +495,20 @@ export declare function buildElementsContext({ parentContext, path, elements, pr
     accessPolicyResource?: AccessPolicyResource;
 }): ElementsContextType | undefined;
 
+/**
+ * Builds the `statusReason` CodeableConcept used when soft-deleting a draft
+ * `MedicationRequest` whose vendor-side outcome is unknown (see
+ * {@link MEDICATION_REQUEST_STATUS_REASON_RESPONSE_NOT_RECEIVED}).
+ *
+ * Paired with `status: 'unknown'` (a valid FHIR R4 MedicationRequest status),
+ * this is the standard shape every order-medication caller should write when
+ * `orderMedication(...)` throws after the draft MR has been created.
+ *
+ * @returns A `CodeableConcept` carrying our canonical system + code and a
+ *   human-readable `text` summary.
+ */
+export declare function buildMedicationRequestResponseLostStatusReason(): CodeableConcept;
+
 export declare function buildTypeName(components: string[]): string;
 
 export declare function businessRule(key: string, message: string): OperationOutcome;
@@ -2172,6 +2189,14 @@ export declare function getImageSrc(resource: Resource): string | undefined;
 
 export declare function getInnerDerivedIdentifierExpression(expression: string): string | undefined;
 
+/**
+ * Reads the medication-order iframe launch URL from MedicationRequest extensions.
+ * @param medicationRequest - MR to read.
+ * @param ext - Vendor extension URL configuration.
+ * @returns The launch URL, if present.
+ */
+export declare function getMedicationOrderIframeUrl(medicationRequest: MedicationRequest, ext: MedicationOrderExtensions): string | undefined;
+
 export declare function getNestedProperty(value: TypedValueWithPath | undefined, key: string, options: {
     profileUrl?: string;
     withPath: true;
@@ -2203,6 +2228,22 @@ export declare function getPathDifference(parentPath: string, path: string): str
  */
 export declare function getPathDisplayName(path: string): string;
 
+/**
+ * Reads the pending medication-order id from MedicationRequest identifiers.
+ * @param medicationRequest - Draft or active MR carrying vendor identifiers.
+ * @param ext - Vendor extension URL and identifier system configuration.
+ * @returns The pending order id string, if present.
+ */
+export declare function getPendingMedicationOrderId(medicationRequest: MedicationRequest, ext: MedicationOrderExtensions): string | undefined;
+
+/**
+ * Reads the pending medication-order status code from MedicationRequest extensions.
+ * @param medicationRequest - MR to read.
+ * @param ext - Vendor extension URL configuration.
+ * @returns The status code (e.g. queued), if present.
+ */
+export declare function getPendingMedicationOrderStatus(medicationRequest: MedicationRequest, ext: MedicationOrderExtensions): string | undefined;
+
 /**
  * Extracts preferred pharmacies from a Patient resource's extensions.
  *
@@ -2904,6 +2945,21 @@ export declare interface InternalTypeSchema {
     mandatoryProperties?: Set<string>;
 }
 
+/**
+ * Stable error when a bot response does not match {@link MedicationOrderResponse}.
+ */
+export declare const INVALID_MEDICATION_ORDER_RESPONSE = "Invalid response from order medication bot";
+
+/**
+ * Stable error when an order-set widget-url response is missing `launchUrl`.
+ */
+export declare const INVALID_MEDICATION_ORDER_SET_RESPONSE = "Invalid response from order-set bot";
+
+/**
+ * Stable error when a bot response is not a Medication array.
+ */
+export declare const INVALID_MEDICATION_SEARCH_RESPONSE = "Invalid response from medication search bot";
+
 export declare function invalidSearchOperator(operator: Operator, searchParameterCodeOrId: string): OperationOutcome;
 
 export declare interface InviteRequest {
@@ -3059,6 +3115,33 @@ export declare function isJwt(token: string): boolean;
 
 export declare function isLowerCase(c: string): boolean;
 
+/**
+ * Type guard: validates an array of Medication resources (drug search bot output).
+ *
+ * Walks every entry rather than spot-checking the first so a tuple-shaped
+ * payload like `[Medication, MedicationRequest]` is rejected (see PR
+ * [#8999](https://github.com/medplum/medplum/pull/8999#discussion_r3276251617)).
+ *
+ * @param value - Unknown bot JSON payload.
+ * @returns True when the value is an array (possibly empty) where every entry
+ *   passes `isResource<Medication>`.
+ */
+export declare function isMedicationArray(value: unknown): value is Medication[];
+
+/**
+ * Type guard: validates an order-medication bot response.
+ * @param value - Unknown bot JSON payload.
+ * @returns True when the value matches MedicationOrderResponse.
+ */
+export declare function isMedicationOrderResponse(value: unknown): value is MedicationOrderResponse;
+
+/**
+ * Type guard: validates an order-set widget-URL bot response.
+ * @param value - Unknown bot JSON payload.
+ * @returns True when the value matches {@link MedicationOrderSetResponse}.
+ */
+export declare function isMedicationOrderSetResponse(value: unknown): value is MedicationOrderSetResponse;
+
 /**
  * Returns true if the access token was issued by a Medplum server.
  * @param accessToken - An access token of unknown origin.
@@ -3588,6 +3671,198 @@ export declare function matchesRange(value: number, range: Range_2, precision?:
  */
 export declare function matchesSearchRequest(resource: Resource, searchRequest: SearchRequest): boolean;
 
+/**
+ * Code stamped on `MedicationRequest.statusReason` when an order-medication
+ * operation never returned a verifiable response — the vendor side may have
+ * created (and sent) the prescription, or it may have rejected the request, and
+ * we cannot tell from the client. Used in place of a hard `DELETE` so the
+ * record stays addressable for later reconciliation against vendor webhooks.
+ */
+export declare const MEDICATION_REQUEST_STATUS_REASON_RESPONSE_NOT_RECEIVED = "response-not-received";
+
+/**
+ * Canonical CodeSystem URL for `MedicationRequest.statusReason` values stamped
+ * by Medplum-managed order flows when a draft MR has to be retired without a
+ * confirmed vendor outcome.
+ *
+ * Downstream reconciliation (vendor webhook bots, audit reports) should match
+ * `statusReason.coding[?(@.system==MEDICATION_REQUEST_STATUS_REASON_SYSTEM)]`
+ * to recognize records that originated from this soft-delete path rather than
+ * a clinician decision.
+ */
+export declare const MEDICATION_REQUEST_STATUS_REASON_SYSTEM = "https://medplum.com/fhir/CodeSystem/medication-request-status-reason";
+
+/**
+ * Vendor-neutral drug line for {@link MedicationOrderRequest}.
+ */
+export declare interface MedicationOrderDrugInput {
+    readonly ndc?: string;
+    readonly rxNorm?: string;
+    readonly routedMedId?: number;
+    readonly quantity: number;
+    readonly quantityQualifier?: string;
+    readonly refill?: number;
+    readonly drugOrder?: number;
+    readonly sigLine3?: string;
+    readonly useSubstitution?: boolean;
+}
+
+/**
+ * Vendor-neutral mapping of the extension URLs / identifier systems used to read
+ * pending medication-order state stamped on a `MedicationRequest`.
+ */
+export declare interface MedicationOrderExtensions {
+    readonly pendingOrderIdSystem: string;
+    readonly pendingOrderStatusUrl: string;
+    readonly iframeUrlExtension: string;
+}
+
+/**
+ * Vendor-neutral input for an order-medication bot (matches the ScriptSure bot shape).
+ */
+export declare interface MedicationOrderRequest {
+    readonly patientId: string;
+    readonly medicationRequestId?: string;
+    readonly combinationMed?: boolean;
+    readonly drugs?: MedicationOrderDrugInput[];
+    readonly compoundTitle?: string;
+    readonly compoundQuantity?: number;
+    readonly compoundQuantityQualifier?: string;
+    readonly compoundSigs?: {
+        readonly sigOrder: number;
+        readonly line3: string;
+        readonly drugId?: number;
+    }[];
+    readonly conditionIds?: string[];
+    readonly coverageId?: string;
+    readonly payerOrganizationId?: string;
+    readonly pharmacyOrganizationId?: string;
+    readonly diagnoses?: {
+        readonly icdId: string;
+        readonly name: string;
+    }[];
+    readonly pharmacyNcpdpId?: string;
+    readonly pharmacyName?: string;
+    readonly writtenDate?: string;
+    readonly fillDate?: string;
+    /** Days supply for ScriptSure pending order duration (used when no draft MR, e.g. compound). */
+    readonly durationDays?: number;
+    /** Notes to pharmacist (ScriptSure pending-order pharmacyNote); also stored on draft MR as `note`. */
+    readonly pharmacyNote?: string;
+    /** Free-text patient instructions (additional sig); maps to dosageInstruction[0].patientInstruction when using MR path. */
+    readonly patientInstruction?: string;
+    readonly appId?: string;
+}
+
+/**
+ * Encodes a {@link MedicationOrderRequest} as a FHIR `Parameters` body for the
+ * vendor-neutral `$order-medication` custom operation.
+ *
+ * Nested arrays (`drugs`, `compoundSigs`, `diagnoses`) are emitted as one
+ * `parameter` entry per element so the OperationDefinition's `max: '*'`
+ * cardinality round-trips; primitive arrays (`conditionIds`) likewise emit
+ * one entry per id. Optional fields are omitted entirely.
+ *
+ * @param req - The order-medication request (vendor-neutral).
+ * @returns A `Parameters` resource ready to POST.
+ */
+export declare function medicationOrderRequestToParameters(req: MedicationOrderRequest): Parameters_2;
+
+/**
+ * Vendor-neutral output from an order-medication bot.
+ */
+export declare interface MedicationOrderResponse {
+    readonly orderId: number;
+    /**
+     * Vendor-side patient id (numeric in ScriptSure today; other vendors may use a different
+     * shape). Kept as `number` for backwards compatibility with the ScriptSure bot output.
+     */
+    readonly vendorPatientId: number;
+    readonly launchUrl: string;
+    readonly medicationRequestId?: string;
+    readonly pendingOrderStatus?: 'queued' | 'reused';
+}
+
+/**
+ * Vendor-neutral input for an order-set widget-URL bot.
+ *
+ * One of `planDefinitionId` (Medplum reverse-lookup to the vendor's orderset id
+ * via a cross-system identifier) or `vendorOrderSetId` (escape hatch when no
+ * synced PD exists) is required. Bots reject input where both are set so the
+ * intent is unambiguous on the wire.
+ */
+export declare interface MedicationOrderSetRequest {
+    readonly patientId: string;
+    readonly planDefinitionId?: string;
+    /**
+     * Vendor-side order-set id. Numeric in ScriptSure today; kept as
+     * `number | string` so vendors with non-numeric ids can adopt the operation
+     * without a wire-format change.
+     */
+    readonly vendorOrderSetId?: number | string;
+    readonly appId?: string;
+}
+
+/**
+ * Encodes a {@link MedicationOrderSetRequest} as a FHIR `Parameters` body for
+ * the vendor-neutral `$order-set-url` custom operation
+ * (`POST /fhir/R4/PlanDefinition/$order-set-url`). Optional fields are omitted
+ * entirely so the wire payload mirrors the legacy `executeBot` plain-JSON
+ * shape the bot's `parseInput` helper would otherwise have to coerce.
+ *
+ * `vendorOrderSetId` is encoded as `valueInteger` when numeric and
+ * `valueString` otherwise — keeping the operation usable by future vendors
+ * whose order-set ids are not numeric.
+ *
+ * @param req - Order-set request (vendor-neutral).
+ * @returns A `Parameters` resource ready to POST.
+ */
+export declare function medicationOrderSetRequestToParameters(req: MedicationOrderSetRequest): Parameters_2;
+
+/**
+ * Vendor-neutral output from an order-set widget-URL bot.
+ *
+ * The bot itself does not create FHIR resources — it just resolves the vendor
+ * ids and returns an iframe URL the prescriber loads to review/sign the whole
+ * order set in one pass. Optional echoes (`vendorPatientId`, `vendorOrderSetId`,
+ * `planDefinitionId`) are surfaced for diagnostics and audit logging.
+ */
+export declare interface MedicationOrderSetResponse {
+    readonly launchUrl: string;
+    readonly vendorPatientId?: number | string;
+    readonly vendorOrderSetId?: number | string;
+    readonly planDefinitionId?: string;
+}
+
+/**
+ * Parameters for a drug search bot used by {@link MedicationOrderRequest} flows.
+ */
+export declare interface MedicationSearchParams {
+    readonly term?: string;
+    readonly ndc?: string;
+    readonly rxNorm?: string;
+    readonly routedMedId?: number;
+    readonly searchOtc?: boolean;
+    readonly searchSupply?: boolean;
+    readonly searchBrand?: boolean;
+    readonly searchGeneric?: boolean;
+    readonly includeCode?: boolean;
+    /** When true, drug-search bot returns quantity qualifiers from GET /v3/prescription/quantityqualifier instead of Medication[]. */
+    readonly quantityQualifiers?: boolean;
+}
+
+/**
+ * Encodes a {@link MedicationSearchParams} as a FHIR `Parameters` body for the
+ * vendor-neutral `$drug-search` (and `$drug-quantity-qualifiers`) custom
+ * operations. Optional fields are omitted entirely so the wire payload stays
+ * minimal and mirrors the legacy `executeBot` plain-JSON shape that the bot's
+ * `parseInput` helper would otherwise have to coerce.
+ *
+ * @param params - Drug search parameters (vendor-neutral subset).
+ * @returns A `Parameters` resource ready to POST.
+ */
+export declare function medicationSearchParamsToParameters(params: MedicationSearchParams): Parameters_2;
+
 export declare const MEDPLUM_CLI_CLIENT_ID = "medplum-cli";
 
 export declare const MEDPLUM_RELEASES_URL = "https://meta.medplum.com/releases";
@@ -4898,6 +5173,13 @@ export declare class MedplumClient extends TypedEventTarget<MedplumClientEventMa
      * @returns The response body.
      */
     startAsyncRequest<T>(url: string, options?: MedplumRequestOptions): Promise<T>;
+    /**
+     * Wraps `fetch` execution with token refresh and retry logic.
+     * @param url - The URL to request
+     * @param options - Optional fetch options
+     * @returns The response
+     */
+    wrappedFetch(url: string, options: RequestInit): Promise<Response>;
     /**
      * Returns the key value client.
      * @returns The key value client.
@@ -4947,7 +5229,6 @@ export declare class MedplumClient extends TypedEventTarget<MedplumClientEventMa
     private deleteCacheEntry;
     /**
      * Makes an HTTP request.
-     * @param method - The HTTP method (GET, POST, etc).
      * @param url - The target URL.
      * @param options - Optional fetch request init options.
      * @param state - Optional request state.
@@ -5006,7 +5287,6 @@ export declare class MedplumClient extends TypedEventTarget<MedplumClientEventMa
      * Handles an unauthenticated response from the server.
      * First, tries to refresh the access token and retry the request.
      * Otherwise, calls unauthenticated callbacks and rejects.
-     * @param method - The HTTP method of the original request.
      * @param url - The URL of the original request.
      * @param options - Optional fetch request init options.
      * @returns The result of the retry.
@@ -6341,6 +6621,30 @@ export declare class OrAtom extends InfixOperatorAtom {
  */
 export declare type OutputRow = Record<string, any>;
 
+/**
+ * Decodes the `Parameters` response from the `$order-medication` custom
+ * operation into a typed {@link MedicationOrderResponse}. Throws
+ * `INVALID_MEDICATION_ORDER_RESPONSE` when required fields are missing.
+ *
+ * @param params - The `Parameters` resource returned by the operation.
+ * @returns A vendor-neutral {@link MedicationOrderResponse}.
+ */
+export declare function parametersToMedicationOrderResponse(params: Parameters_2): MedicationOrderResponse;
+
+/**
+ * Decodes the `Parameters` response from the `$order-set-url` custom operation
+ * into a typed {@link MedicationOrderSetResponse}. Throws
+ * `INVALID_MEDICATION_ORDER_SET_RESPONSE` when `launchUrl` is missing or empty.
+ *
+ * Echoed vendor ids (`vendorPatientId`, `vendorOrderSetId`) are preserved as
+ * the wire type — `number` when sent as `valueInteger`, `string` when sent as
+ * `valueString` — so downstream code can read either without conversion.
+ *
+ * @param params - The `Parameters` resource returned by the operation.
+ * @returns A vendor-neutral {@link MedicationOrderSetResponse}.
+ */
+export declare function parametersToMedicationOrderSetResponse(params: Parameters_2): MedicationOrderSetResponse;
+
 /**
  * Parses a FHIRPath expression into an AST.
  * The result can be used to evaluate the expression against a resource or other object.
@@ -7016,6 +7320,7 @@ export declare class ParserBuilder {
      readonly elementDefinitions?: InternalSchemaElement[];
      readonly parsedExpression: FhirPathAtom;
      readonly array?: boolean;
+     readonly referenceTargetTypes?: ResourceType[];
  }
 
  export declare const SearchParameterType: {