@medplum/react-hooks 5.1.24 → 5.1.27

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';
@@ -106,8 +114,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;
@@ -296,6 +318,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 +448,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 {
@@ -461,14 +532,18 @@ export declare function usePatientSummaryData(patient: Patient | Reference<Patie
  * Encapsulates calls to a search-pharmacy bot and an add-patient-pharmacy bot,
  * and can be composed with the generic `PharmacyDialog` component from `@medplum/react`.
  *
+ * The search param type is generic so vendor hooks can widen it with their own
+ * filters (e.g. ScriptSure `specialties`); the extra keys are passed through to
+ * the bot as-is at runtime.
+ *
  * @param searchBotIdentifier - Bot identifier for the pharmacy search bot.
  * @param addPharmacyBotIdentifier - Bot identifier for the add-patient-pharmacy bot.
  * @returns An object with `searchPharmacies` and `addToFavorites` callbacks.
  */
-export declare function usePharmacySearch(searchBotIdentifier: Identifier, addPharmacyBotIdentifier: Identifier): UsePharmacySearchReturn;
+export declare function usePharmacySearch<T extends PharmacySearchParams = PharmacySearchParams>(searchBotIdentifier: Identifier, addPharmacyBotIdentifier: Identifier): UsePharmacySearchReturn<T>;
 
-export declare interface UsePharmacySearchReturn {
-    searchPharmacies: (params: PharmacySearchParams) => Promise<Organization[]>;
+export declare interface UsePharmacySearchReturn<T extends PharmacySearchParams = PharmacySearchParams> {
+    searchPharmacies: (params: T) => Promise<Organization[]>;
     addToFavorites: (params: AddFavoriteParams) => Promise<AddPharmacyResponse>;
 }
 
@@ -538,6 +613,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.
  *
@@ -611,13 +710,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;
 
@@ -637,6 +741,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 = {
@@ -658,8 +786,22 @@ export declare type UseWhisperResult = {
     start: () => Promise<void>;
     stop: () => void;
     isListening: boolean;
+    muted: boolean;
+    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';
@@ -106,8 +114,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;
@@ -296,6 +318,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 +448,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 {
@@ -461,14 +532,18 @@ export declare function usePatientSummaryData(patient: Patient | Reference<Patie
  * Encapsulates calls to a search-pharmacy bot and an add-patient-pharmacy bot,
  * and can be composed with the generic `PharmacyDialog` component from `@medplum/react`.
  *
+ * The search param type is generic so vendor hooks can widen it with their own
+ * filters (e.g. ScriptSure `specialties`); the extra keys are passed through to
+ * the bot as-is at runtime.
+ *
  * @param searchBotIdentifier - Bot identifier for the pharmacy search bot.
  * @param addPharmacyBotIdentifier - Bot identifier for the add-patient-pharmacy bot.
  * @returns An object with `searchPharmacies` and `addToFavorites` callbacks.
  */
-export declare function usePharmacySearch(searchBotIdentifier: Identifier, addPharmacyBotIdentifier: Identifier): UsePharmacySearchReturn;
+export declare function usePharmacySearch<T extends PharmacySearchParams = PharmacySearchParams>(searchBotIdentifier: Identifier, addPharmacyBotIdentifier: Identifier): UsePharmacySearchReturn<T>;
 
-export declare interface UsePharmacySearchReturn {
-    searchPharmacies: (params: PharmacySearchParams) => Promise<Organization[]>;
+export declare interface UsePharmacySearchReturn<T extends PharmacySearchParams = PharmacySearchParams> {
+    searchPharmacies: (params: T) => Promise<Organization[]>;
     addToFavorites: (params: AddFavoriteParams) => Promise<AddPharmacyResponse>;
 }
 
@@ -538,6 +613,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.
  *
@@ -611,13 +710,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;
 
@@ -637,6 +741,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 = {
@@ -658,8 +786,22 @@ export declare type UseWhisperResult = {
     start: () => Promise<void>;
     stop: () => void;
     isListening: boolean;
+    muted: boolean;
+    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 { }