@medplum/react-hooks 5.1.26 → 5.1.28

package/dist/cjs/index.d.ts

@@ -8,11 +8,18 @@ import type { ExtractResource } from '@medplum/fhirtypes';
 import type { Identifier } from '@medplum/fhirtypes';
 import type { JSX } from 'react';
 import type { Medication } from '@medplum/fhirtypes';
+import type { MedicationCartClearRequest } from '@medplum/core';
+import type { MedicationCartManageResponse } from '@medplum/core';
+import type { MedicationCartRemoveRequest } from '@medplum/core';
+import type { MedicationCheckoutRequest } from '@medplum/core';
+import type { MedicationCheckoutResponse } from '@medplum/core';
 import type { MedicationOrderRequest } from '@medplum/core';
 import type { MedicationOrderResponse } from '@medplum/core';
+import type { MedicationRequest } from '@medplum/fhirtypes';
 import type { MedicationSearchParams } from '@medplum/core';
 import type { MedplumClient } from '@medplum/core';
 import type { OperationOutcome } from '@medplum/fhirtypes';
+import type { OrderSetSyncResponse } from '@medplum/core';
 import type { Organization } from '@medplum/fhirtypes';
 import type { Patient } from '@medplum/fhirtypes';
 import type { PharmacySearchParams } from '@medplum/core';
@@ -30,6 +37,7 @@ import type { ReactNode } from 'react';
 import type { Reference } from '@medplum/fhirtypes';
 import type { Resource } from '@medplum/fhirtypes';
 import type { ResourceArray } from '@medplum/core';
+import type { ResourceModifiedEvent } from '@medplum/core';
 import type { ResourceType } from '@medplum/fhirtypes';
 import type { SearchRequest } from '@medplum/core';
 import type { Signature } from '@medplum/fhirtypes';
@@ -37,6 +45,23 @@ import type { Subscription } from '@medplum/fhirtypes';
 import type { TypedValue } from '@medplum/core';
 import type { WithId } from '@medplum/core';
 
+/**
+ * Applies the `questionnaire-optionExclusive` rule to an answer change.
+ *
+ * Given the previous and newly requested answers for an item, enforces that selecting an answer
+ * option marked exclusive clears every other answer, and selecting any other option clears a
+ * previously selected exclusive answer. Returns the new answers unchanged if the item has no
+ * exclusive options or the change only removed answers.
+ *
+ * See: https://hl7.org/fhir/extensions/StructureDefinition-questionnaire-optionExclusive.html
+ *
+ * @param item - The questionnaire item being answered.
+ * @param previousAnswers - The item's answers before the change.
+ * @param newAnswers - The answers requested by the change.
+ * @returns The reconciled answers.
+ */
+export declare function applyOptionExclusive(item: QuestionnaireItem, previousAnswers: QuestionnaireResponseItemAnswer[] | undefined, newAnswers: QuestionnaireResponseItemAnswer[]): QuestionnaireResponseItemAnswer[];
+
 export declare function buildInitialResponse(questionnaire: Questionnaire, questionnaireResponse?: QuestionnaireResponse): QuestionnaireResponse;
 
 export declare function buildInitialResponseItem(item: QuestionnaireItem): QuestionnaireResponseItem;
@@ -106,8 +131,22 @@ export declare function isChoiceQuestion(item: QuestionnaireItem): boolean;
  */
 export declare function isQuestionEnabled(item: QuestionnaireItem, questionnaireResponse: QuestionnaireResponse | undefined): boolean;
 
+/**
+ * Returns true if an error thrown while expanding a ValueSet means the value set itself is
+ * unavailable — a permanent 400/404 (e.g. "ValueSet not found"). Transient failures (429 rate
+ * limit, 401, 5xx, network) return false so a blip never disables a field.
+ * @param err - The error thrown by `valueSetExpand`.
+ * @returns True for a permanent 400/404, false for a transient failure.
+ */
+export declare function isValueSetUnavailableError(err: unknown): boolean;
+
+/** Thrown by {@link UseMedicationCartReturn.checkout} when an {@link UseMedicationCartReturn.addToCart} call is still in flight. */
+export declare const MEDICATION_CART_ADD_IN_PROGRESS = "Cannot checkout while a medication is still being added to the cart";
+
 export declare interface MedicationIFrameOptions {
     readonly patientId?: string;
+    /** Selected practice location for multi-practice deployments. */
+    readonly organization?: Reference<Organization>;
     readonly onPatientSyncSuccess?: () => void;
     readonly onIframeSuccess?: (url: string) => void;
     readonly onError?: (err: unknown) => void;
@@ -154,6 +193,8 @@ export declare const QUESTIONNAIRE_HIDDEN_URL = "http://hl7.org/fhir/StructureDe
 
 export declare const QUESTIONNAIRE_ITEM_CONTROL_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl";
 
+export declare const QUESTIONNAIRE_OPTION_EXCLUSIVE_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-optionExclusive";
+
 export declare const QUESTIONNAIRE_REFERENCE_FILTER_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-referenceFilter";
 
 export declare const QUESTIONNAIRE_REFERENCE_RESOURCE_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-referenceResource";
@@ -296,6 +337,53 @@ export declare function typedValueToResponseItem(item: QuestionnaireItem, value:
 
 export declare const useCachedBinaryUrl: (binaryUrl: string | undefined) => string | undefined;
 
+/**
+ * Vendor-neutral hook for the full **medication cart** lifecycle: add a draft
+ * line (`createResource`), check out a set of drafts into the vendor's batch
+ * approval queue (`$checkout-medications`), and remove/clear cart lines
+ * (`$remove-cart-medication` / `$clear-cart`).
+ *
+ * Cart checkout / remove / clear hit project-scoped **FHIR custom operations**
+ * whose backing Bot is chosen at deploy time via an `OperationDefinition`
+ * carrying the `operationDefinition-implementation` extension — see
+ * [bot operations docs](https://www.medplum.com/docs/bots/custom-fhir-operations).
+ * The server's `tryCustomOperation` dispatch handles the OD → Bot lookup, so
+ * projects swap vendors by deploying a different bot under the same code.
+ *
+ * `addToCart` is plain FHIR `createResource` (no `$add-cart` operation): the
+ * Medplum-side cart is the set of draft `MedicationRequest`s. Vendor staging
+ * (e.g. ScriptSure MedCart) happens at checkout. Vendors without a batch
+ * approval queue (e.g. DoseSpot iframe-first) simply never call `checkout` /
+ * `removeFromCart` / `clearCart`.
+ *
+ * Requests for the custom operations are encoded as `Parameters` bodies and
+ * decoded by the matching `@medplum/core` helpers. Per-line outcomes arrive in
+ * `response.items`.
+ *
+ * @returns Cart add / checkout / remove / clear callbacks plus `adding` state.
+ */
+export declare function useMedicationCart(): UseMedicationCartReturn;
+
+export declare interface UseMedicationCartReturn {
+    /**
+     * Persist a draft `MedicationRequest` as a cart line via plain FHIR
+     * `createResource` (no custom operation). Vendor staging happens later at
+     * {@link UseMedicationCartReturn.checkout}.
+     */
+    addToCart: (medicationRequest: MedicationRequest) => Promise<MedicationRequest>;
+    /** True while one or more {@link UseMedicationCartReturn.addToCart} calls are in flight. */
+    adding: boolean;
+    /**
+     * Submit draft cart lines to the vendor's batch approval queue and return an
+     * embeddable approval-widget URL. Refuses while {@link UseMedicationCartReturn.adding} is true.
+     */
+    checkout: (input: MedicationCheckoutRequest) => Promise<MedicationCheckoutResponse>;
+    /** Remove a single draft `MedicationRequest` from the patient's vendor cart. */
+    removeFromCart: (input: MedicationCartRemoveRequest) => Promise<MedicationCartManageResponse>;
+    /** Remove every item from the patient's vendor cart. */
+    clearCart: (input: MedicationCartClearRequest) => Promise<MedicationCartManageResponse>;
+}
+
 /**
  * Generic React hook that syncs a patient to a medication-order vendor and
  * returns the chart iframe URL.
@@ -379,6 +467,8 @@ export declare interface UseMedicationOrderSetOptions {
     /** Vendor-side order set id, when picked directly (escape hatch when no synced PD exists yet). */
     readonly vendorOrderSetId?: number | string;
     readonly appId?: string;
+    /** Selected practice location for multi-practice deployments. */
+    readonly organization?: Reference<Organization>;
 }
 
 export declare interface UseMedicationOrderSetReturn {
@@ -523,7 +613,6 @@ export declare interface UseResourceBoardProps<T extends Resource = Resource> {
      * without changing the search. Reloads in place — no skeleton — like `refresh()`.
      */
     readonly reloadKey?: unknown;
-    readonly onSelectFirst?: (item: WithId<T>) => void;
     readonly onLoad?: (items: WithId<T>[], total: number | undefined) => void;
     readonly onError?: (error: unknown) => void;
 }
@@ -542,6 +631,30 @@ export declare interface UseResourceBoardResult<T extends Resource = Resource> {
     readonly refresh: () => Promise<void>;
 }
 
+/**
+ * React hook for observing FHIR resource modifications made through the Medplum client.
+ *
+ * The callback is invoked whenever this client instance creates, updates, patches, or deletes
+ * a resource of one of the given types, including modifications announced with
+ * `MedplumClient.notifyResourceModified`. Use it to keep local component state in sync with
+ * mutations made elsewhere in the application. Subscribing to a single resource type narrows
+ * the event so `event.resource` is typed to that resource, no type guard required:
+ *
+ * ```tsx
+ * useResourceModified('Slot', (event) => {
+ *   // event.resource is `WithId<Slot> | undefined`
+ * });
+ * useResourceModified(['Slot', 'Appointment'], () => refreshSchedule());
+ * ```
+ *
+ * Modifications made by other clients (or other users) are not observed;
+ * use `useSubscription` for server-side change notifications.
+ *
+ * @param resourceType - The resource type or types to observe.
+ * @param callback - Invoked with the event payload for each matching modification.
+ */
+export declare function useResourceModified<K extends ResourceType>(resourceType: K | K[], callback: (event: ResourceModifiedEvent<ExtractResource<K>>) => void): void;
+
 /**
  * React hook for searching FHIR resources.
  *
@@ -615,13 +728,18 @@ export declare type UseSubscriptionOptions = {
  * to the configured e-prescribing vendor via the `$sync-orderset` custom FHIR operation
  * (`POST /fhir/R4/PlanDefinition/$sync-orderset`).
  *
- * Silently no-ops when the operation is not deployed (i.e. no e-prescribing vendor
- * is configured for the project), so callers do not need to guard against missing
- * integrations.
+ * Resolves with the decoded `OrderSetSyncResponse` so callers can surface
+ * per-action failures (`results[i].status === 'failed'` / `failedCount > 0`) —
+ * without this, an order set that only partially synced would silently apply
+ * with fewer meds than the PlanDefinition requested.
  *
- * @returns A stable `syncOrderSet(planDefinitionId)` callback.
+ * Resolves with `undefined` when the operation is not deployed (i.e. no
+ * e-prescribing vendor is configured for the project), so callers do not need to
+ * guard against missing integrations.
+ *
+ * @returns A stable `syncOrderSet(planDefinitionId, organization?)` callback.
  */
-export declare function useSyncOrderSet(): (planDefinitionId: string) => Promise<void>;
+export declare function useSyncOrderSet(): (planDefinitionId: string, organization?: Reference<Organization>) => Promise<OrderSetSyncResponse | undefined>;
 
 export declare function useThreadInbox({ query, threadId }: UseThreadInboxOptions): UseThreadInboxReturn;
 
@@ -641,6 +759,30 @@ export declare interface UseThreadInboxReturn {
     refreshThreadMessages: () => Promise<void>;
 }
 
+/**
+ * Probes a set of ValueSet URLs for availability, each with a filter-free, count-limited expansion.
+ *
+ * A filter-free probe means a 400/404 unambiguously describes the value set itself (unlike a
+ * user-typed search, whose 400 can be filter-specific), so the verdict is safe to act on. Repeated
+ * probes of the same URL are deduplicated by the `MedplumClient` request cache, which caches
+ * rejections too, so many fields bound to the same missing value set cost one request. Recovery
+ * after a value set is imported happens on the next mount (i.e. a page refresh) — there is no live
+ * subscription. Transient failures (429/5xx/network) resolve as available so a blip never disables
+ * a field; only a permanent 400/404 marks a URL unavailable.
+ * @param urls - The ValueSet URLs to probe. Falsy entries are ignored, and duplicates collapse to a
+ * single probe.
+ * @returns The availability verdict, with `loading` true until every requested URL has settled.
+ */
+export declare function useValueSetAvailabilities(urls: readonly (string | undefined)[]): ValueSetAvailability;
+
+/**
+ * Probes a single ValueSet's availability once on mount. A thin wrapper around
+ * {@link useValueSetAvailabilities} for the common single-value-set case.
+ * @param url - The ValueSet URL, or undefined for unbound inputs (always available).
+ * @returns undefined while the probe is in flight, true if available, false if unavailable.
+ */
+export declare function useValueSetAvailability(url: string | undefined): boolean | undefined;
+
 export declare function useWhisper({ language, model, onTranscript, idleTimeoutMs, }: UseWhisperOptions): UseWhisperResult;
 
 export declare type UseWhisperOptions = {
@@ -666,6 +808,18 @@ export declare type UseWhisperResult = {
     setMuted: (value: boolean) => void;
 };
 
+/**
+ * The result of probing one or more ValueSet URLs for availability.
+ */
+export declare interface ValueSetAvailability {
+    /** True while at least one requested URL is still being probed. */
+    readonly loading: boolean;
+    /** The subset of requested URLs known to be available. */
+    readonly available: string[];
+    /** The subset of requested URLs known to be unavailable (a permanent 400/404). */
+    readonly unavailable: string[];
+}
+
 export declare type WhisperStatus = 'idle' | 'requesting_microphone' | 'connecting' | 'connected' | 'listening' | 'speech_started' | 'speech_stopped' | 'disconnected' | 'error';
 
 export { }

package/dist/esm/index.d.ts

@@ -8,11 +8,18 @@ import type { ExtractResource } from '@medplum/fhirtypes';
 import type { Identifier } from '@medplum/fhirtypes';
 import type { JSX } from 'react';
 import type { Medication } from '@medplum/fhirtypes';
+import type { MedicationCartClearRequest } from '@medplum/core';
+import type { MedicationCartManageResponse } from '@medplum/core';
+import type { MedicationCartRemoveRequest } from '@medplum/core';
+import type { MedicationCheckoutRequest } from '@medplum/core';
+import type { MedicationCheckoutResponse } from '@medplum/core';
 import type { MedicationOrderRequest } from '@medplum/core';
 import type { MedicationOrderResponse } from '@medplum/core';
+import type { MedicationRequest } from '@medplum/fhirtypes';
 import type { MedicationSearchParams } from '@medplum/core';
 import type { MedplumClient } from '@medplum/core';
 import type { OperationOutcome } from '@medplum/fhirtypes';
+import type { OrderSetSyncResponse } from '@medplum/core';
 import type { Organization } from '@medplum/fhirtypes';
 import type { Patient } from '@medplum/fhirtypes';
 import type { PharmacySearchParams } from '@medplum/core';
@@ -30,6 +37,7 @@ import type { ReactNode } from 'react';
 import type { Reference } from '@medplum/fhirtypes';
 import type { Resource } from '@medplum/fhirtypes';
 import type { ResourceArray } from '@medplum/core';
+import type { ResourceModifiedEvent } from '@medplum/core';
 import type { ResourceType } from '@medplum/fhirtypes';
 import type { SearchRequest } from '@medplum/core';
 import type { Signature } from '@medplum/fhirtypes';
@@ -37,6 +45,23 @@ import type { Subscription } from '@medplum/fhirtypes';
 import type { TypedValue } from '@medplum/core';
 import type { WithId } from '@medplum/core';
 
+/**
+ * Applies the `questionnaire-optionExclusive` rule to an answer change.
+ *
+ * Given the previous and newly requested answers for an item, enforces that selecting an answer
+ * option marked exclusive clears every other answer, and selecting any other option clears a
+ * previously selected exclusive answer. Returns the new answers unchanged if the item has no
+ * exclusive options or the change only removed answers.
+ *
+ * See: https://hl7.org/fhir/extensions/StructureDefinition-questionnaire-optionExclusive.html
+ *
+ * @param item - The questionnaire item being answered.
+ * @param previousAnswers - The item's answers before the change.
+ * @param newAnswers - The answers requested by the change.
+ * @returns The reconciled answers.
+ */
+export declare function applyOptionExclusive(item: QuestionnaireItem, previousAnswers: QuestionnaireResponseItemAnswer[] | undefined, newAnswers: QuestionnaireResponseItemAnswer[]): QuestionnaireResponseItemAnswer[];
+
 export declare function buildInitialResponse(questionnaire: Questionnaire, questionnaireResponse?: QuestionnaireResponse): QuestionnaireResponse;
 
 export declare function buildInitialResponseItem(item: QuestionnaireItem): QuestionnaireResponseItem;
@@ -106,8 +131,22 @@ export declare function isChoiceQuestion(item: QuestionnaireItem): boolean;
  */
 export declare function isQuestionEnabled(item: QuestionnaireItem, questionnaireResponse: QuestionnaireResponse | undefined): boolean;
 
+/**
+ * Returns true if an error thrown while expanding a ValueSet means the value set itself is
+ * unavailable — a permanent 400/404 (e.g. "ValueSet not found"). Transient failures (429 rate
+ * limit, 401, 5xx, network) return false so a blip never disables a field.
+ * @param err - The error thrown by `valueSetExpand`.
+ * @returns True for a permanent 400/404, false for a transient failure.
+ */
+export declare function isValueSetUnavailableError(err: unknown): boolean;
+
+/** Thrown by {@link UseMedicationCartReturn.checkout} when an {@link UseMedicationCartReturn.addToCart} call is still in flight. */
+export declare const MEDICATION_CART_ADD_IN_PROGRESS = "Cannot checkout while a medication is still being added to the cart";
+
 export declare interface MedicationIFrameOptions {
     readonly patientId?: string;
+    /** Selected practice location for multi-practice deployments. */
+    readonly organization?: Reference<Organization>;
     readonly onPatientSyncSuccess?: () => void;
     readonly onIframeSuccess?: (url: string) => void;
     readonly onError?: (err: unknown) => void;
@@ -154,6 +193,8 @@ export declare const QUESTIONNAIRE_HIDDEN_URL = "http://hl7.org/fhir/StructureDe
 
 export declare const QUESTIONNAIRE_ITEM_CONTROL_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl";
 
+export declare const QUESTIONNAIRE_OPTION_EXCLUSIVE_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-optionExclusive";
+
 export declare const QUESTIONNAIRE_REFERENCE_FILTER_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-referenceFilter";
 
 export declare const QUESTIONNAIRE_REFERENCE_RESOURCE_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-referenceResource";
@@ -296,6 +337,53 @@ export declare function typedValueToResponseItem(item: QuestionnaireItem, value:
 
 export declare const useCachedBinaryUrl: (binaryUrl: string | undefined) => string | undefined;
 
+/**
+ * Vendor-neutral hook for the full **medication cart** lifecycle: add a draft
+ * line (`createResource`), check out a set of drafts into the vendor's batch
+ * approval queue (`$checkout-medications`), and remove/clear cart lines
+ * (`$remove-cart-medication` / `$clear-cart`).
+ *
+ * Cart checkout / remove / clear hit project-scoped **FHIR custom operations**
+ * whose backing Bot is chosen at deploy time via an `OperationDefinition`
+ * carrying the `operationDefinition-implementation` extension — see
+ * [bot operations docs](https://www.medplum.com/docs/bots/custom-fhir-operations).
+ * The server's `tryCustomOperation` dispatch handles the OD → Bot lookup, so
+ * projects swap vendors by deploying a different bot under the same code.
+ *
+ * `addToCart` is plain FHIR `createResource` (no `$add-cart` operation): the
+ * Medplum-side cart is the set of draft `MedicationRequest`s. Vendor staging
+ * (e.g. ScriptSure MedCart) happens at checkout. Vendors without a batch
+ * approval queue (e.g. DoseSpot iframe-first) simply never call `checkout` /
+ * `removeFromCart` / `clearCart`.
+ *
+ * Requests for the custom operations are encoded as `Parameters` bodies and
+ * decoded by the matching `@medplum/core` helpers. Per-line outcomes arrive in
+ * `response.items`.
+ *
+ * @returns Cart add / checkout / remove / clear callbacks plus `adding` state.
+ */
+export declare function useMedicationCart(): UseMedicationCartReturn;
+
+export declare interface UseMedicationCartReturn {
+    /**
+     * Persist a draft `MedicationRequest` as a cart line via plain FHIR
+     * `createResource` (no custom operation). Vendor staging happens later at
+     * {@link UseMedicationCartReturn.checkout}.
+     */
+    addToCart: (medicationRequest: MedicationRequest) => Promise<MedicationRequest>;
+    /** True while one or more {@link UseMedicationCartReturn.addToCart} calls are in flight. */
+    adding: boolean;
+    /**
+     * Submit draft cart lines to the vendor's batch approval queue and return an
+     * embeddable approval-widget URL. Refuses while {@link UseMedicationCartReturn.adding} is true.
+     */
+    checkout: (input: MedicationCheckoutRequest) => Promise<MedicationCheckoutResponse>;
+    /** Remove a single draft `MedicationRequest` from the patient's vendor cart. */
+    removeFromCart: (input: MedicationCartRemoveRequest) => Promise<MedicationCartManageResponse>;
+    /** Remove every item from the patient's vendor cart. */
+    clearCart: (input: MedicationCartClearRequest) => Promise<MedicationCartManageResponse>;
+}
+
 /**
  * Generic React hook that syncs a patient to a medication-order vendor and
  * returns the chart iframe URL.
@@ -379,6 +467,8 @@ export declare interface UseMedicationOrderSetOptions {
     /** Vendor-side order set id, when picked directly (escape hatch when no synced PD exists yet). */
     readonly vendorOrderSetId?: number | string;
     readonly appId?: string;
+    /** Selected practice location for multi-practice deployments. */
+    readonly organization?: Reference<Organization>;
 }
 
 export declare interface UseMedicationOrderSetReturn {
@@ -523,7 +613,6 @@ export declare interface UseResourceBoardProps<T extends Resource = Resource> {
      * without changing the search. Reloads in place — no skeleton — like `refresh()`.
      */
     readonly reloadKey?: unknown;
-    readonly onSelectFirst?: (item: WithId<T>) => void;
     readonly onLoad?: (items: WithId<T>[], total: number | undefined) => void;
     readonly onError?: (error: unknown) => void;
 }
@@ -542,6 +631,30 @@ export declare interface UseResourceBoardResult<T extends Resource = Resource> {
     readonly refresh: () => Promise<void>;
 }
 
+/**
+ * React hook for observing FHIR resource modifications made through the Medplum client.
+ *
+ * The callback is invoked whenever this client instance creates, updates, patches, or deletes
+ * a resource of one of the given types, including modifications announced with
+ * `MedplumClient.notifyResourceModified`. Use it to keep local component state in sync with
+ * mutations made elsewhere in the application. Subscribing to a single resource type narrows
+ * the event so `event.resource` is typed to that resource, no type guard required:
+ *
+ * ```tsx
+ * useResourceModified('Slot', (event) => {
+ *   // event.resource is `WithId<Slot> | undefined`
+ * });
+ * useResourceModified(['Slot', 'Appointment'], () => refreshSchedule());
+ * ```
+ *
+ * Modifications made by other clients (or other users) are not observed;
+ * use `useSubscription` for server-side change notifications.
+ *
+ * @param resourceType - The resource type or types to observe.
+ * @param callback - Invoked with the event payload for each matching modification.
+ */
+export declare function useResourceModified<K extends ResourceType>(resourceType: K | K[], callback: (event: ResourceModifiedEvent<ExtractResource<K>>) => void): void;
+
 /**
  * React hook for searching FHIR resources.
  *
@@ -615,13 +728,18 @@ export declare type UseSubscriptionOptions = {
  * to the configured e-prescribing vendor via the `$sync-orderset` custom FHIR operation
  * (`POST /fhir/R4/PlanDefinition/$sync-orderset`).
  *
- * Silently no-ops when the operation is not deployed (i.e. no e-prescribing vendor
- * is configured for the project), so callers do not need to guard against missing
- * integrations.
+ * Resolves with the decoded `OrderSetSyncResponse` so callers can surface
+ * per-action failures (`results[i].status === 'failed'` / `failedCount > 0`) —
+ * without this, an order set that only partially synced would silently apply
+ * with fewer meds than the PlanDefinition requested.
  *
- * @returns A stable `syncOrderSet(planDefinitionId)` callback.
+ * Resolves with `undefined` when the operation is not deployed (i.e. no
+ * e-prescribing vendor is configured for the project), so callers do not need to
+ * guard against missing integrations.
+ *
+ * @returns A stable `syncOrderSet(planDefinitionId, organization?)` callback.
  */
-export declare function useSyncOrderSet(): (planDefinitionId: string) => Promise<void>;
+export declare function useSyncOrderSet(): (planDefinitionId: string, organization?: Reference<Organization>) => Promise<OrderSetSyncResponse | undefined>;
 
 export declare function useThreadInbox({ query, threadId }: UseThreadInboxOptions): UseThreadInboxReturn;
 
@@ -641,6 +759,30 @@ export declare interface UseThreadInboxReturn {
     refreshThreadMessages: () => Promise<void>;
 }
 
+/**
+ * Probes a set of ValueSet URLs for availability, each with a filter-free, count-limited expansion.
+ *
+ * A filter-free probe means a 400/404 unambiguously describes the value set itself (unlike a
+ * user-typed search, whose 400 can be filter-specific), so the verdict is safe to act on. Repeated
+ * probes of the same URL are deduplicated by the `MedplumClient` request cache, which caches
+ * rejections too, so many fields bound to the same missing value set cost one request. Recovery
+ * after a value set is imported happens on the next mount (i.e. a page refresh) — there is no live
+ * subscription. Transient failures (429/5xx/network) resolve as available so a blip never disables
+ * a field; only a permanent 400/404 marks a URL unavailable.
+ * @param urls - The ValueSet URLs to probe. Falsy entries are ignored, and duplicates collapse to a
+ * single probe.
+ * @returns The availability verdict, with `loading` true until every requested URL has settled.
+ */
+export declare function useValueSetAvailabilities(urls: readonly (string | undefined)[]): ValueSetAvailability;
+
+/**
+ * Probes a single ValueSet's availability once on mount. A thin wrapper around
+ * {@link useValueSetAvailabilities} for the common single-value-set case.
+ * @param url - The ValueSet URL, or undefined for unbound inputs (always available).
+ * @returns undefined while the probe is in flight, true if available, false if unavailable.
+ */
+export declare function useValueSetAvailability(url: string | undefined): boolean | undefined;
+
 export declare function useWhisper({ language, model, onTranscript, idleTimeoutMs, }: UseWhisperOptions): UseWhisperResult;
 
 export declare type UseWhisperOptions = {
@@ -666,6 +808,18 @@ export declare type UseWhisperResult = {
     setMuted: (value: boolean) => void;
 };
 
+/**
+ * The result of probing one or more ValueSet URLs for availability.
+ */
+export declare interface ValueSetAvailability {
+    /** True while at least one requested URL is still being probed. */
+    readonly loading: boolean;
+    /** The subset of requested URLs known to be available. */
+    readonly available: string[];
+    /** The subset of requested URLs known to be unavailable (a permanent 400/404). */
+    readonly unavailable: string[];
+}
+
 export declare type WhisperStatus = 'idle' | 'requesting_microphone' | 'connecting' | 'connected' | 'listening' | 'speech_started' | 'speech_stopped' | 'disconnected' | 'error';
 
 export { }