@openmrs/esm-api 8.0.1-pre.3783 → 8.0.1-pre.3790

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 14 files with swc (87.75ms)
+[0] Successfully compiled: 14 files with swc (100.72ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/current-user.d.ts

@@ -19,18 +19,18 @@ export declare const sessionStore: import("zustand").StoreApi<SessionStore>;
  * Subsequent values will be produced whenever the user object is
  * updated.
  *
- * @param opts An object with `includeAuthStatus` boolean
- *   property that defaults to `false`. When `includeAuthStatus` is set
- *   to `true`, the entire response object from the API will be provided.
- *   When `includeAuthStatus` is set to `false`, only the `user` property
- *   of the response object will be provided.
+ * The function accepts an optional `opts` object with an `includeAuthStatus`
+ * boolean property that defaults to `true`. When `includeAuthStatus` is `true`,
+ * the entire {@link Session} object from the API will be provided. When
+ * `includeAuthStatus` is `false`, only the {@link LoggedInUser} property of the
+ * response object will be provided.
  *
- * @returns An Observable that produces zero or more values (as
- *   described above). The values produced will be a user object (if
- *   `includeAuthStatus` is set to `false`) or an object with a session
- *   and authenticated property (if `includeAuthStatus` is set to `true`).
+ * @returns An Observable that produces zero or more values (as described above).
+ *   The values produced will be a {@link LoggedInUser} object (if `includeAuthStatus`
+ *   is set to `false`) or a {@link Session} object with authentication status
+ *   (if `includeAuthStatus` is set to `true` or not provided).
  *
- * #### Example
+ * @example
  *
  * ```js
  * import { getCurrentUser } from '@openmrs/esm-api'
@@ -50,37 +50,180 @@ export declare const sessionStore: import("zustand").StoreApi<SessionStore>;
  * leak and source of bugs.
  */
 declare function getCurrentUser(): Observable<Session>;
+/**
+ * @param opts Options for controlling the response format.
+ * @param opts.includeAuthStatus When `true`, returns the full {@link Session} object
+ *   including authentication status.
+ * @returns An Observable that produces {@link Session} objects.
+ */
 declare function getCurrentUser(opts: {
     includeAuthStatus: true;
 }): Observable<Session>;
+/**
+ * @param opts Options for controlling the response format.
+ * @param opts.includeAuthStatus When `false`, returns only the {@link LoggedInUser} object
+ *   without the surrounding session information.
+ * @returns An Observable that produces {@link LoggedInUser} objects.
+ */
 declare function getCurrentUser(opts: {
     includeAuthStatus: false;
 }): Observable<LoggedInUser>;
 export { getCurrentUser };
+/**
+ * Returns the global session store containing the current user's session information.
+ * If the session data is stale (older than 1 minute) or not yet loaded, this function
+ * will trigger a refetch of the current user's session.
+ *
+ * @returns The global session store that can be subscribed to for session updates.
+ *
+ * @example
+ * ```ts
+ * import { getSessionStore } from '@openmrs/esm-api';
+ * const store = getSessionStore();
+ * const unsubscribe = store.subscribe((state) => {
+ *   if (state.loaded) {
+ *     console.log('Session:', state.session);
+ *   }
+ * });
+ * ```
+ */
 export declare function getSessionStore(): import("zustand").StoreApi<SessionStore>;
+/**
+ * Sets the document's language attribute based on the user's locale preference
+ * from the session data. This affects the HTML `lang` attribute which is used
+ * for accessibility and internationalization.
+ *
+ * The locale is determined from either the session's locale or the user's
+ * default locale property. Underscores in the locale are converted to hyphens
+ * to match BCP 47 language tag format.
+ *
+ * @param data The session object containing locale information.
+ */
 export declare function setUserLanguage(data: Session): void;
 /**
  * The `refetchCurrentUser` function causes a network request to redownload
  * the user. All subscribers to the current user will be notified of the
  * new users once the new version of the user object is downloaded.
  *
- * @returns The same observable as returned by [[getCurrentUser]].
+ * @returns The same observable as returned by {@link getCurrentUser}.
  *
- * #### Example
+ * @example
  * ```js
  * import { refetchCurrentUser } from '@openmrs/esm-api'
  * refetchCurrentUser()
  * ```
  */
 export declare function refetchCurrentUser(username?: string, password?: string): Promise<SessionStore>;
+/**
+ * Clears the current user session from the session store, setting the session
+ * to an unauthenticated state. This is typically called during logout to reset
+ * the application's authentication state.
+ *
+ * @example
+ * ```ts
+ * import { clearCurrentUser } from '@openmrs/esm-api';
+ * // During logout
+ * clearCurrentUser();
+ * ```
+ */
 export declare function clearCurrentUser(): void;
+/**
+ * Checks whether the given user has access based on the required privilege(s).
+ * A user has access if they have the required privilege(s) or if they are a
+ * "System Developer" (super user). If no privilege is required, access is granted.
+ *
+ * @param requiredPrivilege A single privilege string or an array of privilege strings
+ *   that the user must have. If an array is provided, the user must have ALL privileges.
+ * @param user The user object containing their privileges and roles.
+ * @returns `true` if the user has access, `false` otherwise. Returns `true` if no
+ *   privilege is required, and `false` if the user is undefined but a privilege is required.
+ *
+ * @example
+ * ```ts
+ * import { userHasAccess } from '@openmrs/esm-api';
+ * const hasAccess = userHasAccess('View Patients', currentUser);
+ * const hasMultipleAccess = userHasAccess(['View Patients', 'Edit Patients'], currentUser);
+ * ```
+ */
 export declare function userHasAccess(requiredPrivilege: string | Array<string>, user: {
     privileges: Array<Privilege>;
     roles: Array<Role>;
 }): boolean;
+/**
+ * Returns a Promise that resolves with the currently logged-in user object.
+ * If the user is already loaded in the session store, the Promise resolves immediately.
+ * Otherwise, it subscribes to the session store and resolves when a logged-in user
+ * becomes available.
+ *
+ * @returns A Promise that resolves with the LoggedInUser object once available.
+ *
+ * @example
+ * ```ts
+ * import { getLoggedInUser } from '@openmrs/esm-api';
+ * const user = await getLoggedInUser();
+ * console.log('Logged in as:', user.display);
+ * ```
+ */
 export declare function getLoggedInUser(): Promise<LoggedInUser>;
+/**
+ * Returns a Promise that resolves with the current session location, if one is set.
+ * The session location represents the physical location where the user is currently
+ * working (e.g., a clinic or ward).
+ *
+ * @returns A Promise that resolves with the SessionLocation object, or `undefined`
+ *   if no session location is set.
+ *
+ * @example
+ * ```ts
+ * import { getSessionLocation } from '@openmrs/esm-api';
+ * const location = await getSessionLocation();
+ * if (location) {
+ *   console.log('Current location:', location.display);
+ * }
+ * ```
+ */
 export declare function getSessionLocation(): Promise<SessionLocation | undefined>;
+/**
+ * Sets the session location for the current user. The session location represents
+ * the physical location where the user is working (e.g., a clinic or ward).
+ * This triggers a server request to update the session and refreshes the local
+ * session store.
+ *
+ * @param locationUuid The UUID of the location to set as the session location.
+ * @param abortController An AbortController to allow cancellation of the request.
+ * @returns A Promise that resolves with the updated SessionStore.
+ *
+ * @example
+ * ```ts
+ * import { setSessionLocation } from '@openmrs/esm-api';
+ * const abortController = new AbortController();
+ * await setSessionLocation('location-uuid-here', abortController);
+ * ```
+ */
 export declare function setSessionLocation(locationUuid: string, abortController: AbortController): Promise<any>;
+/**
+ * Updates the user properties for a specific user. User properties are key-value
+ * pairs that store user-specific settings and preferences. After updating the
+ * properties on the server, the current user session is refetched to reflect
+ * the changes.
+ *
+ * @param userUuid The UUID of the user whose properties should be updated.
+ * @param userProperties An object containing the properties to set or update.
+ * @param abortController Optional AbortController to allow cancellation of the request.
+ *   If not provided, a new AbortController is created.
+ * @returns A Promise that resolves with the updated SessionStore after refetching
+ *   the current user.
+ *
+ * @example
+ * ```ts
+ * import { getLoggedInUser, setUserProperties } from '@openmrs/esm-api';
+ * const user = await getLoggedInUser();
+ * await setUserProperties(user.uuid, {
+ *   defaultLocale: 'en_GB',
+ *   customSetting: 'value'
+ * });
+ * ```
+ */
 export declare function setUserProperties(userUuid: string, userProperties: {
     [x: string]: string;
 }, abortController?: AbortController): Promise<SessionStore>;

package/dist/current-user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"current-user.d.ts","sourceRoot":"","sources":["../src/current-user.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAiB,MAAM,SAAS,CAAC;AAEtG,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAErE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,KAAK,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,YAAY,0CAGvB,CAAC;AAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,cAAc,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AAC/C,iBAAS,cAAc,CAAC,IAAI,EAAE;IAAE,iBAAiB,EAAE,IAAI,CAAA;CAAE,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAChF,iBAAS,cAAc,CAAC,IAAI,EAAE;IAAE,iBAAiB,EAAE,KAAK,CAAA;CAAE,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;AAuBtF,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,wBAAgB,eAAe,6CAM9B;AAiBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,QAU5C;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,yBAYtE;AAED,wBAAgB,gBAAgB,SAK/B;AAED,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EACzC,IAAI,EAAE;IAAE,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;CAAE,WAa3D;AAED,wBAAgB,eAAe,0BAmB9B;AAED,wBAAgB,kBAAkB,yCAOjC;AAED,wBAAsB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,CAW7G;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE;IACd,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,EACD,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,YAAY,CAAC,CAcvB"}
+{"version":3,"file":"current-user.d.ts","sourceRoot":"","sources":["../src/current-user.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAiB,MAAM,SAAS,CAAC;AAEtG,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAErE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,KAAK,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,YAAY,0CAGvB,CAAC;AAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,cAAc,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AAC/C;;;;;GAKG;AACH,iBAAS,cAAc,CAAC,IAAI,EAAE;IAAE,iBAAiB,EAAE,IAAI,CAAA;CAAE,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAChF;;;;;GAKG;AACH,iBAAS,cAAc,CAAC,IAAI,EAAE;IAAE,iBAAiB,EAAE,KAAK,CAAA;CAAE,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;AAuBtF,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,6CAM9B;AAiBD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,QAU5C;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,yBAYtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,SAK/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EACzC,IAAI,EAAE;IAAE,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;CAAE,WAa3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,0BAmB9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,yCAOjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,CAW7G;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE;IACd,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,EACD,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,YAAY,CAAC,CAcvB"}

package/dist/current-user.js

@@ -31,7 +31,24 @@ function getCurrentUser(opts = {
     });
 }
 export { getCurrentUser };
-export function getSessionStore() {
+/**
+ * Returns the global session store containing the current user's session information.
+ * If the session data is stale (older than 1 minute) or not yet loaded, this function
+ * will trigger a refetch of the current user's session.
+ *
+ * @returns The global session store that can be subscribed to for session updates.
+ *
+ * @example
+ * ```ts
+ * import { getSessionStore } from '@openmrs/esm-api';
+ * const store = getSessionStore();
+ * const unsubscribe = store.subscribe((state) => {
+ *   if (state.loaded) {
+ *     console.log('Session:', state.session);
+ *   }
+ * });
+ * ```
+ */ export function getSessionStore() {
     if (lastFetchTimeMillis < Date.now() - 1000 * 60 || !sessionStore.getState().loaded) {
         refetchCurrentUser();
     }
@@ -49,7 +66,17 @@ function isValidLocale(locale) {
     }
     return true;
 }
-export function setUserLanguage(data) {
+/**
+ * Sets the document's language attribute based on the user's locale preference
+ * from the session data. This affects the HTML `lang` attribute which is used
+ * for accessibility and internationalization.
+ *
+ * The locale is determined from either the session's locale or the user's
+ * default locale property. Underscores in the locale are converted to hyphens
+ * to match BCP 47 language tag format.
+ *
+ * @param data The session object containing locale information.
+ */ export function setUserLanguage(data) {
     let locale = data.locale ?? data.user?.userProperties?.defaultLocale;
     if (locale && locale.includes('_')) {
         locale = locale.replaceAll('_', '-');
@@ -81,9 +108,9 @@ function isSuperUser(user) {
  * the user. All subscribers to the current user will be notified of the
  * new users once the new version of the user object is downloaded.
  *
- * @returns The same observable as returned by [[getCurrentUser]].
+ * @returns The same observable as returned by {@link getCurrentUser}.
  *
- * #### Example
+ * @example
  * ```js
  * import { refetchCurrentUser } from '@openmrs/esm-api'
  * refetchCurrentUser()
@@ -98,7 +125,18 @@ function isSuperUser(user) {
         headers
     }));
 }
-export function clearCurrentUser() {
+/**
+ * Clears the current user session from the session store, setting the session
+ * to an unauthenticated state. This is typically called during logout to reset
+ * the application's authentication state.
+ *
+ * @example
+ * ```ts
+ * import { clearCurrentUser } from '@openmrs/esm-api';
+ * // During logout
+ * clearCurrentUser();
+ * ```
+ */ export function clearCurrentUser() {
     sessionStore.setState({
         loaded: true,
         session: {
@@ -107,7 +145,24 @@ export function clearCurrentUser() {
         }
     });
 }
-export function userHasAccess(requiredPrivilege, user) {
+/**
+ * Checks whether the given user has access based on the required privilege(s).
+ * A user has access if they have the required privilege(s) or if they are a
+ * "System Developer" (super user). If no privilege is required, access is granted.
+ *
+ * @param requiredPrivilege A single privilege string or an array of privilege strings
+ *   that the user must have. If an array is provided, the user must have ALL privileges.
+ * @param user The user object containing their privileges and roles.
+ * @returns `true` if the user has access, `false` otherwise. Returns `true` if no
+ *   privilege is required, and `false` if the user is undefined but a privilege is required.
+ *
+ * @example
+ * ```ts
+ * import { userHasAccess } from '@openmrs/esm-api';
+ * const hasAccess = userHasAccess('View Patients', currentUser);
+ * const hasMultipleAccess = userHasAccess(['View Patients', 'Edit Patients'], currentUser);
+ * ```
+ */ export function userHasAccess(requiredPrivilege, user) {
     if (user === undefined) {
         // if the user hasn't been loaded, then return false iff there is a required privilege
         return !Boolean(requiredPrivilege);
@@ -118,7 +173,21 @@ export function userHasAccess(requiredPrivilege, user) {
     }
     return userHasPrivilege(requiredPrivilege, user) || isSuperUser(user);
 }
-export function getLoggedInUser() {
+/**
+ * Returns a Promise that resolves with the currently logged-in user object.
+ * If the user is already loaded in the session store, the Promise resolves immediately.
+ * Otherwise, it subscribes to the session store and resolves when a logged-in user
+ * becomes available.
+ *
+ * @returns A Promise that resolves with the LoggedInUser object once available.
+ *
+ * @example
+ * ```ts
+ * import { getLoggedInUser } from '@openmrs/esm-api';
+ * const user = await getLoggedInUser();
+ * console.log('Logged in as:', user.display);
+ * ```
+ */ export function getLoggedInUser() {
     let user;
     let unsubscribe;
     return new Promise((res)=>{
@@ -137,7 +206,23 @@ export function getLoggedInUser() {
         }
     });
 }
-export function getSessionLocation() {
+/**
+ * Returns a Promise that resolves with the current session location, if one is set.
+ * The session location represents the physical location where the user is currently
+ * working (e.g., a clinic or ward).
+ *
+ * @returns A Promise that resolves with the SessionLocation object, or `undefined`
+ *   if no session location is set.
+ *
+ * @example
+ * ```ts
+ * import { getSessionLocation } from '@openmrs/esm-api';
+ * const location = await getSessionLocation();
+ * if (location) {
+ *   console.log('Current location:', location.display);
+ * }
+ * ```
+ */ export function getSessionLocation() {
     return new Promise((res, rej)=>{
         const sub = getCurrentUser().subscribe((session)=>{
             res(session.sessionLocation);
@@ -145,7 +230,23 @@ export function getSessionLocation() {
         sub.unsubscribe();
     });
 }
-export async function setSessionLocation(locationUuid, abortController) {
+/**
+ * Sets the session location for the current user. The session location represents
+ * the physical location where the user is working (e.g., a clinic or ward).
+ * This triggers a server request to update the session and refreshes the local
+ * session store.
+ *
+ * @param locationUuid The UUID of the location to set as the session location.
+ * @param abortController An AbortController to allow cancellation of the request.
+ * @returns A Promise that resolves with the updated SessionStore.
+ *
+ * @example
+ * ```ts
+ * import { setSessionLocation } from '@openmrs/esm-api';
+ * const abortController = new AbortController();
+ * await setSessionLocation('location-uuid-here', abortController);
+ * ```
+ */ export async function setSessionLocation(locationUuid, abortController) {
     return handleSessionResponse(openmrsFetch(sessionEndpoint, {
         method: 'POST',
         body: {
@@ -157,7 +258,29 @@ export async function setSessionLocation(locationUuid, abortController) {
         signal: abortController.signal
     }));
 }
-export async function setUserProperties(userUuid, userProperties, abortController) {
+/**
+ * Updates the user properties for a specific user. User properties are key-value
+ * pairs that store user-specific settings and preferences. After updating the
+ * properties on the server, the current user session is refetched to reflect
+ * the changes.
+ *
+ * @param userUuid The UUID of the user whose properties should be updated.
+ * @param userProperties An object containing the properties to set or update.
+ * @param abortController Optional AbortController to allow cancellation of the request.
+ *   If not provided, a new AbortController is created.
+ * @returns A Promise that resolves with the updated SessionStore after refetching
+ *   the current user.
+ *
+ * @example
+ * ```ts
+ * import { getLoggedInUser, setUserProperties } from '@openmrs/esm-api';
+ * const user = await getLoggedInUser();
+ * await setUserProperties(user.uuid, {
+ *   defaultLocale: 'en_GB',
+ *   customSetting: 'value'
+ * });
+ * ```
+ */ export async function setUserProperties(userUuid, userProperties, abortController) {
     if (!abortController) {
         abortController = new AbortController();
     }

package/dist/openmrs-backend-dependencies.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Defines the minimum required versions of OpenMRS backend modules that the
+ * frontend framework depends on. These versions are checked at startup to ensure
+ * compatibility between the frontend and backend.
+ */
 export declare const backendDependencies: {
     'webservices.rest': string;
     fhir2: string;

package/dist/openmrs-backend-dependencies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openmrs-backend-dependencies.d.ts","sourceRoot":"","sources":["../src/openmrs-backend-dependencies.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB;;;CAG/B,CAAC"}
+{"version":3,"file":"openmrs-backend-dependencies.d.ts","sourceRoot":"","sources":["../src/openmrs-backend-dependencies.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;CAG/B,CAAC"}

package/dist/openmrs-backend-dependencies.js

@@ -1,4 +1,8 @@
-export const backendDependencies = {
+/**
+ * Defines the minimum required versions of OpenMRS backend modules that the
+ * frontend framework depends on. These versions are checked at startup to ensure
+ * compatibility between the frontend and backend.
+ */ export const backendDependencies = {
     'webservices.rest': '2.24.0',
     fhir2: '1.0.0-SNAPSHOT'
 };

package/dist/openmrs-fetch.d.ts

@@ -1,13 +1,20 @@
 /** @module @category API */
 import { Observable } from 'rxjs';
 import type { FetchResponse } from './types';
+/** The base URL for the OpenMRS REST API (e.g., '/ws/rest/v1'). */
 export declare const restBaseUrl = "/ws/rest/v1";
+/** The base URL for the OpenMRS FHIR R4 API (e.g., '/ws/fhir2/R4'). */
 export declare const fhirBaseUrl = "/ws/fhir2/R4";
+/** The endpoint for session management operations. */
 export declare const sessionEndpoint = "/ws/rest/v1/session";
 /**
  * Append `path` to the OpenMRS SPA base.
  *
- * #### Example
+ * @param path The path to append to the OpenMRS base URL.
+ * @returns The full URL with the OpenMRS base prepended. If the path is already
+ *   an absolute URL (starting with 'http'), it is returned unchanged.
+ *
+ * @example
  *
  * ```ts
  * makeUrl('/foo/bar');
@@ -33,7 +40,7 @@ export declare function makeUrl(path: string): string;
  *   downloaded the HTTP response body as json, and has an additional
  *   `data` property with the HTTP response json as a javascript object.
  *
- * #### Example
+ * @example
  * ```js
  * import { openmrsFetch } from '@openmrs/esm-api'
  * const abortController = new AbortController();
@@ -76,7 +83,7 @@ export declare function openmrsFetch<T = any>(path: string, fetchInit?: FetchCon
  * @returns An Observable that produces exactly one Response object.
  * The response object is exactly the same as for [[openmrsFetch]].
  *
- * #### Example
+ * @example
  *
  * ```js
  * import { openmrsObservableFetch } from '@openmrs/esm-api'

package/dist/openmrs-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openmrs-fetch.d.ts","sourceRoot":"","sources":["../src/openmrs-fetch.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAIlC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAC1C,eAAO,MAAM,eAAe,wBAA2B,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,UASnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,WAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CA8J1G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,WAAgB,gCA8BjF;AAED,qBAAa,iBAAkB,SAAQ,KAAM,YAAW,UAAU;gBACpD,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,EAAE,iBAAiB,EAAE,KAAK;IAQxG,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACxE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAC3B;AAED,KAAK,YAAY,GAAG,MAAM,GAAG,iBAAiB,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,UAAU,SAAS;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC"}
+{"version":3,"file":"openmrs-fetch.d.ts","sourceRoot":"","sources":["../src/openmrs-fetch.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAIlC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,mEAAmE;AACnE,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,uEAAuE;AACvE,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAC1C,sDAAsD;AACtD,eAAO,MAAM,eAAe,wBAA2B,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,UASnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,WAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CA8J1G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,WAAgB,gCA8BjF;AAED,qBAAa,iBAAkB,SAAQ,KAAM,YAAW,UAAU;gBACpD,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,EAAE,iBAAiB,EAAE,KAAK;IAQxG,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACxE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAC3B;AAED,KAAK,YAAY,GAAG,MAAM,GAAG,iBAAiB,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,UAAU,SAAS;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC"}

package/dist/openmrs-fetch.js

@@ -16,13 +16,17 @@ import { isPlainObject } from "lodash-es";
 import { getConfig } from "@openmrs/esm-config";
 import { clearHistory, navigate } from "@openmrs/esm-navigation";
 import { defaultRedirectAuthFailureUrl } from "./config-schema.js";
-export const restBaseUrl = '/ws/rest/v1';
-export const fhirBaseUrl = '/ws/fhir2/R4';
-export const sessionEndpoint = `${restBaseUrl}/session`;
+/** The base URL for the OpenMRS REST API (e.g., '/ws/rest/v1'). */ export const restBaseUrl = '/ws/rest/v1';
+/** The base URL for the OpenMRS FHIR R4 API (e.g., '/ws/fhir2/R4'). */ export const fhirBaseUrl = '/ws/fhir2/R4';
+/** The endpoint for session management operations. */ export const sessionEndpoint = `${restBaseUrl}/session`;
 /**
  * Append `path` to the OpenMRS SPA base.
  *
- * #### Example
+ * @param path The path to append to the OpenMRS base URL.
+ * @returns The full URL with the OpenMRS base prepended. If the path is already
+ *   an absolute URL (starting with 'http'), it is returned unchanged.
+ *
+ * @example
  *
  * ```ts
  * makeUrl('/foo/bar');
@@ -55,7 +59,7 @@ export const sessionEndpoint = `${restBaseUrl}/session`;
  *   downloaded the HTTP response body as json, and has an additional
  *   `data` property with the HTTP response json as a javascript object.
  *
- * #### Example
+ * @example
  * ```js
  * import { openmrsFetch } from '@openmrs/esm-api'
  * const abortController = new AbortController();
@@ -218,7 +222,7 @@ export const sessionEndpoint = `${restBaseUrl}/session`;
  * @returns An Observable that produces exactly one Response object.
  * The response object is exactly the same as for [[openmrsFetch]].
  *
- * #### Example
+ * @example
  *
  * ```js
  * import { openmrsObservableFetch } from '@openmrs/esm-api'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-api",
-  "version": "8.0.1-pre.3783",
+  "version": "8.0.1-pre.3790",
   "license": "MPL-2.0",
   "description": "The javascript module for interacting with the OpenMRS API",
   "type": "module",
@@ -62,10 +62,10 @@
     "@openmrs/esm-navigation": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-config": "8.0.1-pre.3783",
-    "@openmrs/esm-error-handling": "8.0.1-pre.3783",
-    "@openmrs/esm-globals": "8.0.1-pre.3783",
-    "@openmrs/esm-navigation": "8.0.1-pre.3783",
+    "@openmrs/esm-config": "8.0.1-pre.3790",
+    "@openmrs/esm-error-handling": "8.0.1-pre.3790",
+    "@openmrs/esm-globals": "8.0.1-pre.3790",
+    "@openmrs/esm-navigation": "8.0.1-pre.3790",
     "@swc/cli": "^0.7.7",
     "@swc/core": "^1.11.29",
     "@vitest/coverage-v8": "^4.0.7",

package/src/current-user.ts

@@ -33,18 +33,18 @@ let lastFetchTimeMillis = 0;
  * Subsequent values will be produced whenever the user object is
  * updated.
  *
- * @param opts An object with `includeAuthStatus` boolean
- *   property that defaults to `false`. When `includeAuthStatus` is set
- *   to `true`, the entire response object from the API will be provided.
- *   When `includeAuthStatus` is set to `false`, only the `user` property
- *   of the response object will be provided.
+ * The function accepts an optional `opts` object with an `includeAuthStatus`
+ * boolean property that defaults to `true`. When `includeAuthStatus` is `true`,
+ * the entire {@link Session} object from the API will be provided. When
+ * `includeAuthStatus` is `false`, only the {@link LoggedInUser} property of the
+ * response object will be provided.
  *
- * @returns An Observable that produces zero or more values (as
- *   described above). The values produced will be a user object (if
- *   `includeAuthStatus` is set to `false`) or an object with a session
- *   and authenticated property (if `includeAuthStatus` is set to `true`).
+ * @returns An Observable that produces zero or more values (as described above).
+ *   The values produced will be a {@link LoggedInUser} object (if `includeAuthStatus`
+ *   is set to `false`) or a {@link Session} object with authentication status
+ *   (if `includeAuthStatus` is set to `true` or not provided).
  *
- * #### Example
+ * @example
  *
  * ```js
  * import { getCurrentUser } from '@openmrs/esm-api'
@@ -64,7 +64,19 @@ let lastFetchTimeMillis = 0;
  * leak and source of bugs.
  */
 function getCurrentUser(): Observable<Session>;
+/**
+ * @param opts Options for controlling the response format.
+ * @param opts.includeAuthStatus When `true`, returns the full {@link Session} object
+ *   including authentication status.
+ * @returns An Observable that produces {@link Session} objects.
+ */
 function getCurrentUser(opts: { includeAuthStatus: true }): Observable<Session>;
+/**
+ * @param opts Options for controlling the response format.
+ * @param opts.includeAuthStatus When `false`, returns only the {@link LoggedInUser} object
+ *   without the surrounding session information.
+ * @returns An Observable that produces {@link LoggedInUser} objects.
+ */
 function getCurrentUser(opts: { includeAuthStatus: false }): Observable<LoggedInUser>;
 function getCurrentUser(opts = { includeAuthStatus: true }): Observable<Session | LoggedInUser> {
   if (lastFetchTimeMillis < Date.now() - 1000 * 60 || !sessionStore.getState().loaded) {
@@ -90,6 +102,24 @@ function getCurrentUser(opts = { includeAuthStatus: true }): Observable<Session
 
 export { getCurrentUser };
 
+/**
+ * Returns the global session store containing the current user's session information.
+ * If the session data is stale (older than 1 minute) or not yet loaded, this function
+ * will trigger a refetch of the current user's session.
+ *
+ * @returns The global session store that can be subscribed to for session updates.
+ *
+ * @example
+ * ```ts
+ * import { getSessionStore } from '@openmrs/esm-api';
+ * const store = getSessionStore();
+ * const unsubscribe = store.subscribe((state) => {
+ *   if (state.loaded) {
+ *     console.log('Session:', state.session);
+ *   }
+ * });
+ * ```
+ */
 export function getSessionStore() {
   if (lastFetchTimeMillis < Date.now() - 1000 * 60 || !sessionStore.getState().loaded) {
     refetchCurrentUser();
@@ -113,6 +143,17 @@ function isValidLocale(locale: unknown): locale is string {
   return true;
 }
 
+/**
+ * Sets the document's language attribute based on the user's locale preference
+ * from the session data. This affects the HTML `lang` attribute which is used
+ * for accessibility and internationalization.
+ *
+ * The locale is determined from either the session's locale or the user's
+ * default locale property. Underscores in the locale are converted to hyphens
+ * to match BCP 47 language tag format.
+ *
+ * @param data The session object containing locale information.
+ */
 export function setUserLanguage(data: Session) {
   let locale = data.locale ?? data.user?.userProperties?.defaultLocale;
 
@@ -152,9 +193,9 @@ function isSuperUser(user: { roles: Array<Role> }) {
  * the user. All subscribers to the current user will be notified of the
  * new users once the new version of the user object is downloaded.
  *
- * @returns The same observable as returned by [[getCurrentUser]].
+ * @returns The same observable as returned by {@link getCurrentUser}.
  *
- * #### Example
+ * @example
  * ```js
  * import { refetchCurrentUser } from '@openmrs/esm-api'
  * refetchCurrentUser()
@@ -174,6 +215,18 @@ export function refetchCurrentUser(username?: string, password?: string) {
   );
 }
 
+/**
+ * Clears the current user session from the session store, setting the session
+ * to an unauthenticated state. This is typically called during logout to reset
+ * the application's authentication state.
+ *
+ * @example
+ * ```ts
+ * import { clearCurrentUser } from '@openmrs/esm-api';
+ * // During logout
+ * clearCurrentUser();
+ * ```
+ */
 export function clearCurrentUser() {
   sessionStore.setState({
     loaded: true,
@@ -181,6 +234,24 @@ export function clearCurrentUser() {
   });
 }
 
+/**
+ * Checks whether the given user has access based on the required privilege(s).
+ * A user has access if they have the required privilege(s) or if they are a
+ * "System Developer" (super user). If no privilege is required, access is granted.
+ *
+ * @param requiredPrivilege A single privilege string or an array of privilege strings
+ *   that the user must have. If an array is provided, the user must have ALL privileges.
+ * @param user The user object containing their privileges and roles.
+ * @returns `true` if the user has access, `false` otherwise. Returns `true` if no
+ *   privilege is required, and `false` if the user is undefined but a privilege is required.
+ *
+ * @example
+ * ```ts
+ * import { userHasAccess } from '@openmrs/esm-api';
+ * const hasAccess = userHasAccess('View Patients', currentUser);
+ * const hasMultipleAccess = userHasAccess(['View Patients', 'Edit Patients'], currentUser);
+ * ```
+ */
 export function userHasAccess(
   requiredPrivilege: string | Array<string>,
   user: { privileges: Array<Privilege>; roles: Array<Role> },
@@ -198,6 +269,21 @@ export function userHasAccess(
   return userHasPrivilege(requiredPrivilege, user) || isSuperUser(user);
 }
 
+/**
+ * Returns a Promise that resolves with the currently logged-in user object.
+ * If the user is already loaded in the session store, the Promise resolves immediately.
+ * Otherwise, it subscribes to the session store and resolves when a logged-in user
+ * becomes available.
+ *
+ * @returns A Promise that resolves with the LoggedInUser object once available.
+ *
+ * @example
+ * ```ts
+ * import { getLoggedInUser } from '@openmrs/esm-api';
+ * const user = await getLoggedInUser();
+ * console.log('Logged in as:', user.display);
+ * ```
+ */
 export function getLoggedInUser() {
   let user: LoggedInUser;
   let unsubscribe: () => void;
@@ -219,6 +305,23 @@ export function getLoggedInUser() {
   });
 }
 
+/**
+ * Returns a Promise that resolves with the current session location, if one is set.
+ * The session location represents the physical location where the user is currently
+ * working (e.g., a clinic or ward).
+ *
+ * @returns A Promise that resolves with the SessionLocation object, or `undefined`
+ *   if no session location is set.
+ *
+ * @example
+ * ```ts
+ * import { getSessionLocation } from '@openmrs/esm-api';
+ * const location = await getSessionLocation();
+ * if (location) {
+ *   console.log('Current location:', location.display);
+ * }
+ * ```
+ */
 export function getSessionLocation() {
   return new Promise<SessionLocation | undefined>((res, rej) => {
     const sub = getCurrentUser().subscribe((session) => {
@@ -228,6 +331,23 @@ export function getSessionLocation() {
   });
 }
 
+/**
+ * Sets the session location for the current user. The session location represents
+ * the physical location where the user is working (e.g., a clinic or ward).
+ * This triggers a server request to update the session and refreshes the local
+ * session store.
+ *
+ * @param locationUuid The UUID of the location to set as the session location.
+ * @param abortController An AbortController to allow cancellation of the request.
+ * @returns A Promise that resolves with the updated SessionStore.
+ *
+ * @example
+ * ```ts
+ * import { setSessionLocation } from '@openmrs/esm-api';
+ * const abortController = new AbortController();
+ * await setSessionLocation('location-uuid-here', abortController);
+ * ```
+ */
 export async function setSessionLocation(locationUuid: string, abortController: AbortController): Promise<any> {
   return handleSessionResponse(
     openmrsFetch(sessionEndpoint, {
@@ -241,6 +361,29 @@ export async function setSessionLocation(locationUuid: string, abortController:
   );
 }
 
+/**
+ * Updates the user properties for a specific user. User properties are key-value
+ * pairs that store user-specific settings and preferences. After updating the
+ * properties on the server, the current user session is refetched to reflect
+ * the changes.
+ *
+ * @param userUuid The UUID of the user whose properties should be updated.
+ * @param userProperties An object containing the properties to set or update.
+ * @param abortController Optional AbortController to allow cancellation of the request.
+ *   If not provided, a new AbortController is created.
+ * @returns A Promise that resolves with the updated SessionStore after refetching
+ *   the current user.
+ *
+ * @example
+ * ```ts
+ * import { getLoggedInUser, setUserProperties } from '@openmrs/esm-api';
+ * const user = await getLoggedInUser();
+ * await setUserProperties(user.uuid, {
+ *   defaultLocale: 'en_GB',
+ *   customSetting: 'value'
+ * });
+ * ```
+ */
 export async function setUserProperties(
   userUuid: string,
   userProperties: {

package/src/openmrs-backend-dependencies.ts

@@ -1,3 +1,8 @@
+/**
+ * Defines the minimum required versions of OpenMRS backend modules that the
+ * frontend framework depends on. These versions are checked at startup to ensure
+ * compatibility between the frontend and backend.
+ */
 export const backendDependencies = {
   'webservices.rest': '2.24.0',
   fhir2: '1.0.0-SNAPSHOT',

package/src/openmrs-fetch.ts

@@ -6,14 +6,21 @@ import { clearHistory, navigate } from '@openmrs/esm-navigation';
 import type { FetchResponse } from './types';
 import { defaultRedirectAuthFailureUrl, type EsmApiConfigObject } from './config-schema';
 
+/** The base URL for the OpenMRS REST API (e.g., '/ws/rest/v1'). */
 export const restBaseUrl = '/ws/rest/v1';
+/** The base URL for the OpenMRS FHIR R4 API (e.g., '/ws/fhir2/R4'). */
 export const fhirBaseUrl = '/ws/fhir2/R4';
+/** The endpoint for session management operations. */
 export const sessionEndpoint = `${restBaseUrl}/session`;
 
 /**
  * Append `path` to the OpenMRS SPA base.
  *
- * #### Example
+ * @param path The path to append to the OpenMRS base URL.
+ * @returns The full URL with the OpenMRS base prepended. If the path is already
+ *   an absolute URL (starting with 'http'), it is returned unchanged.
+ *
+ * @example
  *
  * ```ts
  * makeUrl('/foo/bar');
@@ -49,7 +56,7 @@ export function makeUrl(path: string) {
  *   downloaded the HTTP response body as json, and has an additional
  *   `data` property with the HTTP response json as a javascript object.
  *
- * #### Example
+ * @example
  * ```js
  * import { openmrsFetch } from '@openmrs/esm-api'
  * const abortController = new AbortController();
@@ -251,7 +258,7 @@ export function openmrsFetch<T = any>(path: string, fetchInit: FetchConfig = {})
  * @returns An Observable that produces exactly one Response object.
  * The response object is exactly the same as for [[openmrsFetch]].
  *
- * #### Example
+ * @example
  *
  * ```js
  * import { openmrsObservableFetch } from '@openmrs/esm-api'