@medplum/core 5.1.38 → 5.1.40

package/dist/esm/index.d.ts

@@ -2,6 +2,7 @@ import type { AccessPolicy } from '@medplum/fhirtypes';
 import type { AccessPolicyResource } from '@medplum/fhirtypes';
 import type { Address } from '@medplum/fhirtypes';
 import type { Agent } from '@medplum/fhirtypes';
+import type { Appointment } from '@medplum/fhirtypes';
 import type { Attachment } from '@medplum/fhirtypes';
 import type { Binary } from '@medplum/fhirtypes';
 import type { Bot } from '@medplum/fhirtypes';
@@ -27,6 +28,7 @@ import type { HealthcareService } from '@medplum/fhirtypes';
 import type { HumanName } from '@medplum/fhirtypes';
 import type { Identifier } from '@medplum/fhirtypes';
 import type { ImagingStudy } from '@medplum/fhirtypes';
+import type { Location as Location_2 } from '@medplum/fhirtypes';
 import type { Media } from '@medplum/fhirtypes';
 import type { Medication } from '@medplum/fhirtypes';
 import type { MedicationRequest } from '@medplum/fhirtypes';
@@ -827,22 +829,40 @@ export declare function checkForNull(value: unknown, path: string, issues: Opera
  */
 export declare function checkIfValidMedplumVersion(appName: string, version: string): Promise<boolean>;
 
+/**
+ * Immutably clears one scheduling parameter a HealthcareService sets for itself, dropping it back to
+ * whatever scheduling defaults that parameter to.
+ * @param service - HealthcareService to update
+ * @param url - Url of the SchedulingParameters sub-extension to remove, for example `duration`
+ * @returns A cloned HealthcareService without the matching parameter
+ */
+export declare function clearHealthcareServiceSchedulingParameter<T extends HealthcareService>(service: T, url: HealthcareServiceSchedulingParameterUrl): T;
+
 /**
  * Clears the locally-cached `ReleaseManifest`s for all versions.
  */
 export declare function clearReleaseCache(): void;
 
 /**
- * Immutably clears one scheduling parameter a Schedule sets for a HealthcareService, dropping that
- * calendar back to the service-level parameter of the same name. Pairs with `setScheduleParameter`
- * and `getScheduleParameters`.
+ * Immutably clears one scheduling parameter a Schedule overrides for a HealthcareService.
  * @param schedule - Schedule to update
- * @param service - HealthcareService referenced by the parameters
+ * @param service - HealthcareService the parameters are scoped to
  * @param url - Url of the SchedulingParameters sub-extension to remove, for example `availability`
  * @returns A cloned Schedule without the matching parameter
+ * @deprecated Use clearScheduleSchedulingParameter() instead.
  */
 export declare function clearScheduleParameter(schedule: Schedule, service: WithId<HealthcareService>, url: string): Schedule;
 
+/**
+ * Immutably clears one scheduling parameter a Schedule overrides for a HealthcareService, dropping that
+ * calendar back to the service-level parameter of the same name.
+ * @param schedule - Schedule to update
+ * @param service - HealthcareService the parameters are scoped to
+ * @param url - Url of the SchedulingParameters sub-extension to remove, for example `availability`
+ * @returns A cloned Schedule without the matching parameter
+ */
+export declare function clearScheduleSchedulingParameter<T extends Schedule>(schedule: T, service: WithId<HealthcareService>, url: SchedulingParameterUrl): T;
+
 /**
  * Log level for MedplumClient requests and responses.
  * - 'none': No logging
@@ -1712,7 +1732,9 @@ export declare function extractAccountReferences(meta: Meta | undefined): Refere
  * @param serviceType - CodeableConcept values to inspect
  * @returns HealthcareService references embedded in the concepts
  */
-export declare function extractServiceTypeReferences(serviceType: CodeableConcept[] | undefined): Reference<HealthcareService>[];
+export declare function extractServiceTypeReferences(serviceType: CodeableConcept[] | undefined): (Reference<HealthcareService> & {
+    reference: string;
+})[];
 
 /**
  * Fetches the version strings for all published Medplum releases.
@@ -2456,6 +2478,16 @@ export declare function getAllDataTypes(): DataTypesMap;
  */
 export declare function getAllQuestionnaireAnswers(response: QuestionnaireResponse): Record<string, QuestionnaireResponseItemAnswer[]>;
 
+/**
+ * Reads the site an appointment is held at.
+ *
+ * Finds the entry {@link toAppointmentSiteReference} stamped.
+ *
+ * @param appointment - The appointment to read.
+ * @returns The site, or undefined for an appointment holding none.
+ */
+export declare function getAppointmentSite(appointment: Appointment): Reference<Location_2> | undefined;
+
 /**
  * Returns the global Buffer constructor if available.
  * @returns The Buffer constructor or undefined.
@@ -2548,6 +2580,17 @@ export declare function getExtensions(extensible: Extensible | undefined, urlOrU
  */
 export declare function getExtensionValue(resource: any, ...urls: string[]): ExtensionValue | undefined;
 
+/**
+ * Reads one scheduling parameter a HealthcareService sets for itself.
+ *
+ * This is the raw sub-extension as stored. The server resolves what the service actually schedules by,
+ * applying defaults, in its own `getHealthcareServiceSchedulingParameters`.
+ * @param service - HealthcareService to inspect
+ * @param url - Url of the SchedulingParameters sub-extension to read, for example `duration`
+ * @returns Every matching sub-extension, in document order
+ */
+export declare function getHealthcareServiceSchedulingParameters(service: HealthcareService, url: HealthcareServiceSchedulingParameterUrl): Extension[];
+
 /**
  * Returns the resource identifier for the given system.
  *
@@ -2709,18 +2752,28 @@ export declare function getReferenceString(input: Reference | Resource): string
 export declare function getResourceTypes(): ResourceType[];
 
 /**
- * Reads one scheduling parameter a Schedule sets for a HealthcareService, taking precedence over the
- * service-level parameter of the same name. Pairs with `setScheduleParameter` and `clearScheduleParameter`.
- *
- * The result is a list rather than a single extension because a Schedule may carry more than one
- * SchedulingParameters extension matching the service, and because a parameter may legitimately repeat.
+ * Reads one scheduling parameter a Schedule sets for a HealthcareService.
  * @param schedule - Schedule to inspect
- * @param service - HealthcareService referenced by the parameters
+ * @param service - HealthcareService the parameters are scoped to
  * @param url - Url of the SchedulingParameters sub-extension to read, for example `availability`
  * @returns Every matching sub-extension, in document order
+ * @deprecated Use getScheduleSchedulingParameters() instead.
  */
 export declare function getScheduleParameters(schedule: Schedule, service: WithId<HealthcareService>, url: string): Extension[];
 
+/**
+ * Reads one scheduling parameter a Schedule sets for a HealthcareService, which overrides the
+ * service-level parameter of the same name.
+ *
+ * This is the raw sub-extension as stored. The server resolves what a calendar actually schedules by,
+ * applying defaults and service-level inheritance, in its own `getScheduleSchedulingParameters`.
+ * @param schedule - Schedule to inspect
+ * @param service - HealthcareService the parameters are scoped to
+ * @param url - Url of the SchedulingParameters sub-extension to read, for example `availability`
+ * @returns Every matching sub-extension, in document order
+ */
+export declare function getScheduleSchedulingParameters(schedule: Schedule, service: WithId<HealthcareService>, url: SchedulingParameterUrl): Extension[];
+
 /**
  * Returns what a visit type must be given before it can be booked, from its
  * `HealthcareService.eligibility` codes.
@@ -2853,13 +2906,25 @@ export declare interface GoogleLoginRequest extends BaseLoginRequest {
 /**
  * Returns whether a Schedule or HealthcareService has a SchedulingParameters extension.
  *
- * Unscoped: on a Schedule, where the extension repeats once per service, this reports that some
- * service is configured rather than any particular one. Ask `getScheduleParameters` about a service.
+ * On a Schedule the extension repeats once per service, so this reports only that some service is
+ * configured; ask `getScheduleSchedulingParameters` about a particular one.
  * @param resource - Schedule or HealthcareService to inspect
  * @returns True if the resource has a SchedulingParameters extension
  */
 export declare function hasSchedulingParameters(resource: Schedule | HealthcareService): boolean;
 
+/** A `SchedulingParameters` sub-extension a HealthcareService may carry. */
+export declare type HealthcareServiceSchedulingParameterExtension = Extension & {
+    url: HealthcareServiceSchedulingParameterUrl;
+};
+
+/**
+ * The sub-extension urls a HealthcareService's own `SchedulingParameters` may carry. `availability` is
+ * excluded because scheduling reads a service's hours from `HealthcareService.availableTime` and rejects
+ * the sub-extension outright.
+ */
+export declare type HealthcareServiceSchedulingParameterUrl = Exclude<SchedulingParameterUrl, 'availability'>;
+
 export declare const HL7_V2_0203 = "http://terminology.hl7.org/CodeSystem/v2-0203";
 
 export declare interface Hl7AckOptions {
@@ -3423,6 +3488,12 @@ export declare function intersection(objects: ArrayLike<{
     [index: string]: any;
 }>): string[];
 
+/**
+ * Stable error when a cart-read bot response does not match
+ * {@link MedicationCartContentsResponse}.
+ */
+export declare const INVALID_MEDICATION_CART_CONTENTS_RESPONSE = "Invalid response from get-cart bot";
+
 /**
  * Stable error when a cart-management bot response does not match
  * {@link MedicationCartManageResponse}.
@@ -3640,6 +3711,13 @@ export declare function isLowerCase(c: string): boolean;
  */
 export declare function isMedicationArray(value: unknown): value is Medication[];
 
+/**
+ * Type guard: validates a cart-read bot response.
+ * @param value - Unknown bot JSON payload.
+ * @returns True when the value matches {@link MedicationCartContentsResponse}.
+ */
+export declare function isMedicationCartContentsResponse(value: unknown): value is MedicationCartContentsResponse;
+
 /**
  * Type guard: validates a cart-management bot response.
  * @param value - Unknown bot JSON payload.
@@ -4256,6 +4334,40 @@ export declare interface MedicationCartClearRequest {
  */
 export declare function medicationCartClearRequestToParameters(req: MedicationCartClearRequest): Parameters_2;
 
+/** Vendor-neutral input to read the patient's vendor cart (`$get-cart`). */
+export declare interface MedicationCartContentsRequest {
+    readonly patientId: string;
+}
+
+/**
+ * Encodes a {@link MedicationCartContentsRequest} as a FHIR `Parameters` body
+ * for the `$get-cart` custom operation. No `action` discriminator: unlike
+ * remove/clear, this operation has its own read-only bot.
+ *
+ * @param req - Cart-contents request (vendor-neutral).
+ * @returns A `Parameters` resource ready to POST.
+ */
+export declare function medicationCartContentsRequestToParameters(req: MedicationCartContentsRequest): Parameters_2;
+
+/**
+ * Vendor-neutral view of the patient's cart as the vendor holds it, reconciled
+ * against local drafts.
+ *
+ * `vendorTotal` is what the prescriber will see in the approval widget;
+ * `draftCount` is what the local record says. They diverge whenever `items`
+ * contains a line that is not `in-sync` or `not-staged` — the drift a
+ * draft-derived cart badge cannot detect on its own.
+ */
+export declare interface MedicationCartContentsResponse {
+    /** Vendor-side patient id (numeric in ScriptSure today). */
+    readonly vendorPatientId: number;
+    readonly vendorTotal: number;
+    readonly draftCount: number;
+    /** True when the vendor reports the cart locked; a write may conflict. */
+    readonly locked: boolean;
+    readonly items: MedicationCartLine[];
+}
+
 /**
  * Per-item outcome from a cart remove/clear. `removed` = the vendor cart item
  * was deleted; `not-in-cart` = the draft was not staged (nothing to remove);
@@ -4269,6 +4381,40 @@ export declare interface MedicationCartItemResult {
     readonly error?: string;
 }
 
+/** One reconciled line in a {@link MedicationCartContentsResponse}. */
+export declare interface MedicationCartLine {
+    readonly status: MedicationCartLineStatus;
+    /** Local draft id; absent for `vendor-only` lines. */
+    readonly medicationRequestId?: string;
+    /** Vendor cart-item reference; absent for `not-staged` drafts. */
+    readonly vendorLineId?: string;
+    /** Display fields off the vendor line; absent for `not-staged` drafts (render those from the draft). */
+    readonly drugName?: string;
+    readonly ndc?: string;
+    readonly rxnorm?: string;
+    readonly quantity?: number;
+    /** Vendor readiness hint (e.g. `Ready`, `Incomplete`); not a guarantee the line will send. */
+    readonly validationState?: string;
+    /** Who staged the line, per the vendor. Identifies the source of an unexpected line. */
+    readonly createdBy?: string;
+    readonly createdAt?: string;
+}
+
+/**
+ * Reconciliation verdict for one cart line, comparing what the vendor holds
+ * against the local draft `MedicationRequest`s:
+ *
+ * - `in-sync`: the vendor line matches a draft. The normal case.
+ * - `vendor-only`: the vendor holds a line with no local draft — staged through
+ *   another UI or by a session whose draft is gone. The prescriber will still
+ *   see it in the approval widget, so a draft-derived cart count under-reports.
+ * - `not-staged`: a draft that has not been checked out yet, so the vendor
+ *   legitimately does not hold it. Benign, not drift.
+ * - `missing-from-vendor`: a draft the vendor no longer holds. Resolves the
+ *   ambiguity left by a failed `removeFromCart`: the line really is gone.
+ */
+export declare type MedicationCartLineStatus = 'in-sync' | 'vendor-only' | 'not-staged' | 'missing-from-vendor';
+
 /**
  * Vendor-neutral output from a cart remove/clear: the vendor patient id, the
  * number of cart items actually removed, and the per-line outcomes (one for a
@@ -7101,6 +7247,13 @@ export declare class MemoryStorage implements Storage {
 
 export declare type Message = string | ArrayBuffer | Blob | ArrayBufferView;
 
+/**
+ * Converts minutes to a SchedulingParameters duration, the inverse of `schedulingDurationToMinutes`.
+ * @param minutes - The length in minutes.
+ * @returns A duration scheduling accepts.
+ */
+export declare function minutesToSchedulingDuration(minutes: number): Duration;
+
 export declare class MissingError extends Error {
     path: string;
     constructor(path: string);
@@ -7469,6 +7622,17 @@ export declare interface OrderSetSyncSequenceResult {
  */
 export declare type OutputRow = Record<string, any>;
 
+/**
+ * Decodes the `Parameters` response from the `$get-cart` custom operation into
+ * a typed {@link MedicationCartContentsResponse}. Throws
+ * {@link INVALID_MEDICATION_CART_CONTENTS_RESPONSE} when required top-level
+ * fields are missing.
+ *
+ * @param params - The `Parameters` resource returned by the operation.
+ * @returns A vendor-neutral {@link MedicationCartContentsResponse}.
+ */
+export declare function parametersToMedicationCartContentsResponse(params: Parameters_2): MedicationCartContentsResponse;
+
 /**
  * Decodes the `Parameters` response from the `$remove-cart-medication` /
  * `$clear-cart` custom operations into a typed {@link MedicationCartManageResponse}.
@@ -8377,14 +8541,28 @@ export declare class ParserBuilder {
  /** Extension on an Appointment recording that medical necessity was confirmed when it was booked. */
  export declare const SchedulingMedicalNecessityURI = "https://medplum.com/fhir/StructureDefinition/SchedulingMedicalNecessity";
 
+ /** A `SchedulingParameters` sub-extension a Schedule may carry. */
+ export declare type SchedulingParameterExtension = Extension & {
+     url: SchedulingParameterUrl;
+ };
+
  export declare const SchedulingParametersURI = "https://medplum.com/fhir/StructureDefinition/SchedulingParameters";
 
+ /**
+  * The sub-extension urls a `SchedulingParameters` extension may carry, apart from the `service` pointer a
+  * Schedule's parameters are matched by, which these helpers maintain rather than expose.
+  */
+ export declare type SchedulingParameterUrl = 'availability' | 'duration' | 'bufferBefore' | 'bufferAfter' | 'alignmentInterval' | 'alignmentOffset' | 'alignmentTimezone' | 'timezone' | 'slotCapacity';
+
  export declare const SchedulingPlanDefinitionURI = "https://medplum.com/fhir/StructureDefinition/SchedulingPlanDefinition";
 
  export declare type SchedulingRequirement = (typeof SCHEDULING_REQUIREMENT_CODES)[number];
 
  export declare const SchedulingScheduleColorURI = "https://medplum.com/fhir/StructureDefinition/SchedulingColor";
 
+ /** Extension URI marking which `Appointment.supportingInformation` entry is the site. */
+ export declare const SchedulingSiteURI = "https://medplum.com/fhir/StructureDefinition/SchedulingSite";
+
  /**
   * This extension is set on `Slot` resources created through scheduling APIs.
   * Its value is a positive integer recording the slotCapacity for the service
@@ -8395,6 +8573,16 @@ export declare class ParserBuilder {
   */
  export declare const SchedulingSlotCapacityURI = "https://medplum.com/fhir/StructureDefinition/SchedulingSlotCapacity";
 
+ /**
+  * This extension marks an `Appointment` created without the scheduling rules being
+  * applied: the time may be occupied or blocked, past the configured capacity, off the
+  * configured start interval, or any length at all.
+  *
+  * Such an appointment is written through the FHIR CRUD API rather than `$book`, so
+  * nothing else about it says that it was never checked. This records only that.
+  */
+ export declare const SchedulingUnvalidatedBookingURI = "https://medplum.com/fhir/StructureDefinition/SchedulingUnvalidatedBooking";
+
  export declare interface SearchableToken {
      readonly system: string | undefined;
      readonly value: string | undefined;
@@ -8521,6 +8709,15 @@ export declare class ParserBuilder {
   */
  export declare function setCodeBySystem(concept: CodeableConcept, system: string, code: string): void;
 
+ /**
+  * Immutably sets one scheduling parameter on a HealthcareService, replacing whatever it already holds at
+  * the sub-extension's url.
+  * @param service - HealthcareService to update
+  * @param subextension - SchedulingParameters sub-extension to set
+  * @returns A cloned HealthcareService containing the parameter
+  */
+ export declare function setHealthcareServiceSchedulingParameter<T extends HealthcareService>(service: T, subextension: HealthcareServiceSchedulingParameterExtension): T;
+
  /**
   * Sets a resource identifier for the given system.
   *
@@ -8554,22 +8751,25 @@ export declare class ParserBuilder {
  export declare function setRateLimitReset(outcome: OperationOutcome, msBeforeNext: number): void;
 
  /**
-  * Immutably sets one scheduling parameter on a Schedule for a HealthcareService, so that calendar keeps
-  * it in place of the service-level parameter of the same name. Whatever the Schedule already holds at the
-  * sub-extension's url is replaced, and the SchedulingParameters extension is created if the Schedule has
-  * none for the service yet.
-  *
-  * Untyped by design, taking any sub-extension of the shape the parameter calls for, for example
-  * `{ url: 'bufferBefore', valueDuration: { value: 10, unit: 'min' } }`. A parameter whose value is a nested
-  * structure rather than a single `value[x]` is worth a typed wrapper over this; `availability` has one in
-  * `@medplum/react-scheduling`. Pairs with `clearScheduleParameter` and `getScheduleParameters`.
+  * Immutably sets one scheduling parameter a Schedule overrides for a HealthcareService.
   * @param schedule - Schedule to update
-  * @param service - HealthcareService referenced by the parameters
+  * @param service - HealthcareService the parameters are scoped to
   * @param subextension - SchedulingParameters sub-extension to set
   * @returns A cloned Schedule containing the parameter
+  * @deprecated Use setScheduleSchedulingParameter() instead.
   */
  export declare function setScheduleParameter(schedule: Schedule, service: WithId<HealthcareService>, subextension: Extension): Schedule;
 
+ /**
+  * Immutably sets one scheduling parameter a Schedule overrides for a HealthcareService, replacing whatever
+  * that calendar already holds at the sub-extension's url.
+  * @param schedule - Schedule to update
+  * @param service - HealthcareService the parameters are scoped to
+  * @param subextension - SchedulingParameters sub-extension to set
+  * @returns A cloned Schedule containing the parameter
+  */
+ export declare function setScheduleSchedulingParameter<T extends Schedule>(schedule: T, service: WithId<HealthcareService>, subextension: SchedulingParameterExtension): T;
+
  export declare function singleton(collection: TypedValue[], type?: string): TypedValue | undefined;
 
  export declare function singularize<T>(value: T | T[] | undefined): T | undefined;
@@ -8930,6 +9130,20 @@ export declare class ParserBuilder {
 
  export declare const TimezoneExtensionURI = "http://hl7.org/fhir/StructureDefinition/timezone";
 
+ /**
+  * Builds the `supportingInformation` entry recording the site an appointment is held at.
+  *
+  * A site and a room are both `Location`, so the site is recorded here rather than as a
+  * participant: `Appointment.location` answers the room, and {@link getAppointmentSite}
+  * the site. Anything writing an appointment outside the booking form should record the
+  * site through this, so that it is identifiable among the other `supportingInformation`
+  * entries.
+  *
+  * @param site - The site the appointment is held at.
+  * @returns The reference, stamped with {@link SchedulingSiteURI}.
+  */
+ export declare function toAppointmentSiteReference(site: WithId<Location_2>): Reference<Location_2>;
+
  /**
   * Converts unknown object into a JavaScript boolean.
   * Note that this is different than the FHIRPath "toBoolean",