@openmrs/esm-emr-api 10.0.1-pre.5434 → 10.0.1-pre.5452

package/.turbo/turbo-build.log

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

package/dist/attachments.d.ts

@@ -18,12 +18,17 @@ export declare const attachmentUrl = "/ws/rest/v1/attachment";
  */
 export declare function getAttachmentByUuid(attachmentUuid: string, abortController: AbortController): Promise<import("@openmrs/esm-api").FetchResponse<any>>;
 /**
- * Fetches all attachments for a specific patient from the OpenMRS server.
+ * Fetches attachments for a specific patient from the OpenMRS server.
  *
  * @param patientUuid The UUID of the patient whose attachments should be fetched.
  * @param includeEncounterless Whether to include attachments that are not associated
- *   with any encounter.
+ *   with any encounter. Ignored when `encounterUuid` is set.
  * @param abortController An AbortController to allow cancellation of the request.
+ * @param encounterUuid When set, only attachments recorded on this encounter are returned.
+ *   The `includeEncounterless` parameter is not sent in that case, because the server
+ *   ignores the encounter filter whenever `includeEncounterless` is present. Pass a UUID
+ *   the server can resolve: an unknown encounter UUID makes the server fall back to every
+ *   attachment of the patient, encounterless ones included.
  * @returns A Promise that resolves with the FetchResponse containing an array of attachments.
  *
  * @example
@@ -32,9 +37,21 @@ export declare function getAttachmentByUuid(attachmentUuid: string, abortControl
  * const abortController = new AbortController();
  * const response = await getAttachments('patient-uuid', true, abortController);
  * console.log(response.data.results);
+ *
+ * const forEncounter = await getAttachments('patient-uuid', false, abortController, 'encounter-uuid');
  * ```
  */
-export declare function getAttachments(patientUuid: string, includeEncounterless: boolean, abortController: AbortController): Promise<import("@openmrs/esm-api").FetchResponse<any>>;
+export declare function getAttachments(patientUuid: string, includeEncounterless: boolean, abortController: AbortController, encounterUuid?: string): Promise<import("@openmrs/esm-api").FetchResponse<any>>;
+/**
+ * Builds the attachment search URL for a patient. Used by `getAttachments` and `useAttachments`
+ * so both request (and cache under) the same key.
+ *
+ * @param patientUuid The UUID of the patient whose attachments should be fetched.
+ * @param includeEncounterless Whether to include attachments that are not associated
+ *   with any encounter. Ignored when `encounterUuid` is set.
+ * @param encounterUuid When set, restricts the search to attachments on this encounter.
+ */
+export declare function getAttachmentsUrl(patientUuid: string, includeEncounterless: boolean, encounterUuid?: string): string;
 /**
  * Creates a new attachment for a patient by uploading a file to the OpenMRS server.
  * The file can be provided either as a File object or as base64-encoded content.
@@ -43,6 +60,8 @@ export declare function getAttachments(patientUuid: string, includeEncounterless
  * @param fileToUpload An object containing the file data and metadata to upload.
  *   Should include `file` (File object) or `base64Content`, plus `fileName` and
  *   `fileDescription`.
+ * @param encounterUuid Optional UUID of an existing encounter to record the attachment on.
+ *   When omitted the attachment is saved without an encounter.
  * @returns A Promise that resolves with the FetchResponse containing the created
  *   attachment data.
  *
@@ -54,9 +73,12 @@ export declare function getAttachments(patientUuid: string, includeEncounterless
  *   fileName: 'document.pdf',
  *   fileDescription: 'Patient consent form'
  * });
+ *
+ * // Record the attachment on a specific encounter
+ * await createAttachment('patient-uuid', uploadedFile, 'encounter-uuid');
  * ```
  */
-export declare function createAttachment(patientUuid: string, fileToUpload: UploadedFile): Promise<import("@openmrs/esm-api").FetchResponse<any>>;
+export declare function createAttachment(patientUuid: string, fileToUpload: UploadedFile, encounterUuid?: string): Promise<import("@openmrs/esm-api").FetchResponse<any>>;
 /**
  * Permanently deletes an attachment from the OpenMRS server. This action cannot
  * be undone.

package/dist/attachments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,qDAAqD;AACrD,eAAO,MAAM,aAAa,2BAA8B,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,0DAI3F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,0DAIlH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,0DAiBrF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,0DAKnG"}
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,qDAAqD;AACrD,eAAO,MAAM,aAAa,2BAA8B,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,0DAI3F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,oBAAoB,EAAE,OAAO,EAC7B,eAAe,EAAE,eAAe,EAChC,aAAa,CAAC,EAAE,MAAM,0DAKvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,UAK3G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,0DAqB7G;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,0DAKnG"}

package/dist/attachments.js

@@ -20,12 +20,17 @@
     });
 }
 /**
- * Fetches all attachments for a specific patient from the OpenMRS server.
+ * Fetches attachments for a specific patient from the OpenMRS server.
  *
  * @param patientUuid The UUID of the patient whose attachments should be fetched.
  * @param includeEncounterless Whether to include attachments that are not associated
- *   with any encounter.
+ *   with any encounter. Ignored when `encounterUuid` is set.
  * @param abortController An AbortController to allow cancellation of the request.
+ * @param encounterUuid When set, only attachments recorded on this encounter are returned.
+ *   The `includeEncounterless` parameter is not sent in that case, because the server
+ *   ignores the encounter filter whenever `includeEncounterless` is present. Pass a UUID
+ *   the server can resolve: an unknown encounter UUID makes the server fall back to every
+ *   attachment of the patient, encounterless ones included.
  * @returns A Promise that resolves with the FetchResponse containing an array of attachments.
  *
  * @example
@@ -34,12 +39,28 @@
  * const abortController = new AbortController();
  * const response = await getAttachments('patient-uuid', true, abortController);
  * console.log(response.data.results);
+ *
+ * const forEncounter = await getAttachments('patient-uuid', false, abortController, 'encounter-uuid');
  * ```
- */ export function getAttachments(patientUuid, includeEncounterless, abortController) {
-    return openmrsFetch(`${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`, {
+ */ export function getAttachments(patientUuid, includeEncounterless, abortController, encounterUuid) {
+    return openmrsFetch(getAttachmentsUrl(patientUuid, includeEncounterless, encounterUuid), {
         signal: abortController.signal
     });
 }
+/**
+ * Builds the attachment search URL for a patient. Used by `getAttachments` and `useAttachments`
+ * so both request (and cache under) the same key.
+ *
+ * @param patientUuid The UUID of the patient whose attachments should be fetched.
+ * @param includeEncounterless Whether to include attachments that are not associated
+ *   with any encounter. Ignored when `encounterUuid` is set.
+ * @param encounterUuid When set, restricts the search to attachments on this encounter.
+ */ export function getAttachmentsUrl(patientUuid, includeEncounterless, encounterUuid) {
+    if (encounterUuid) {
+        return `${attachmentUrl}?patient=${patientUuid}&encounter=${encounterUuid}`;
+    }
+    return `${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`;
+}
 /**
  * Creates a new attachment for a patient by uploading a file to the OpenMRS server.
  * The file can be provided either as a File object or as base64-encoded content.
@@ -48,6 +69,8 @@
  * @param fileToUpload An object containing the file data and metadata to upload.
  *   Should include `file` (File object) or `base64Content`, plus `fileName` and
  *   `fileDescription`.
+ * @param encounterUuid Optional UUID of an existing encounter to record the attachment on.
+ *   When omitted the attachment is saved without an encounter.
  * @returns A Promise that resolves with the FetchResponse containing the created
  *   attachment data.
  *
@@ -59,11 +82,17 @@
  *   fileName: 'document.pdf',
  *   fileDescription: 'Patient consent form'
  * });
+ *
+ * // Record the attachment on a specific encounter
+ * await createAttachment('patient-uuid', uploadedFile, 'encounter-uuid');
  * ```
- */ export async function createAttachment(patientUuid, fileToUpload) {
+ */ export async function createAttachment(patientUuid, fileToUpload, encounterUuid) {
     const formData = new FormData();
     formData.append('fileCaption', fileToUpload.fileDescription);
     formData.append('patient', patientUuid);
+    if (encounterUuid) {
+        formData.append('encounter', encounterUuid);
+    }
     if (fileToUpload.file) {
         formData.append('file', fileToUpload.file, fileToUpload.fileName);
     } else {

package/mock-jest.ts

@@ -2,6 +2,12 @@ export const setCurrentVisit = jest.fn();
 export const attachmentUrl = '/ws/rest/v1/attachment';
 export const getAttachmentByUuid = jest.fn();
 export const getAttachments = jest.fn();
+export const getAttachmentsUrl = jest.fn(
+  (patientUuid: string, includeEncounterless: boolean, encounterUuid?: string) =>
+    encounterUuid
+      ? `${attachmentUrl}?patient=${patientUuid}&encounter=${encounterUuid}`
+      : `${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`,
+);
 export const createAttachment = jest.fn();
 export const deleteAttachmentPermanently = jest.fn();
 export const updateVisit = jest.fn();

package/mock.ts

@@ -4,6 +4,11 @@ export const setCurrentVisit = vi.fn();
 export const attachmentUrl = '/ws/rest/v1/attachment';
 export const getAttachmentByUuid = vi.fn();
 export const getAttachments = vi.fn();
+export const getAttachmentsUrl = vi.fn((patientUuid: string, includeEncounterless: boolean, encounterUuid?: string) =>
+  encounterUuid
+    ? `${attachmentUrl}?patient=${patientUuid}&encounter=${encounterUuid}`
+    : `${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`,
+);
 export const createAttachment = vi.fn();
 export const deleteAttachmentPermanently = vi.fn();
 export const updateVisit = vi.fn();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-emr-api",
-  "version": "10.0.1-pre.5434",
+  "version": "10.0.1-pre.5452",
   "license": "MPL-2.0",
   "description": "The javascript module for interacting with the OpenMRS API",
   "type": "module",
@@ -58,14 +58,14 @@
     "lodash-es": "^4.17.21"
   },
   "peerDependencies": {
-    "@openmrs/esm-api": "^10.0.1-pre.5434",
-    "@openmrs/esm-offline": "^10.0.1-pre.5434",
-    "@openmrs/esm-state": "^10.0.1-pre.5434"
+    "@openmrs/esm-api": "^10.0.1-pre.5452",
+    "@openmrs/esm-offline": "^10.0.1-pre.5452",
+    "@openmrs/esm-state": "^10.0.1-pre.5452"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "10.0.1-pre.5434",
-    "@openmrs/esm-offline": "10.0.1-pre.5434",
-    "@openmrs/esm-state": "10.0.1-pre.5434",
+    "@openmrs/esm-api": "10.0.1-pre.5452",
+    "@openmrs/esm-offline": "10.0.1-pre.5452",
+    "@openmrs/esm-state": "10.0.1-pre.5452",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/attachments.test.ts

@@ -0,0 +1,105 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { openmrsFetch } from '@openmrs/esm-api';
+import { attachmentUrl, createAttachment, getAttachments, getAttachmentsUrl } from './attachments';
+
+vi.mock('@openmrs/esm-api', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@openmrs/esm-api')>()),
+  openmrsFetch: vi.fn(),
+}));
+
+const mockOpenmrsFetch = vi.mocked(openmrsFetch);
+
+describe('getAttachmentsUrl', () => {
+  it('filters by patient and includeEncounterless by default', () => {
+    expect(getAttachmentsUrl('patient-uuid', true)).toBe(
+      `${attachmentUrl}?patient=patient-uuid&includeEncounterless=true`,
+    );
+    expect(getAttachmentsUrl('patient-uuid', false)).toBe(
+      `${attachmentUrl}?patient=patient-uuid&includeEncounterless=false`,
+    );
+  });
+
+  it('filters by encounter and drops includeEncounterless when an encounter is given', () => {
+    expect(getAttachmentsUrl('patient-uuid', true, 'encounter-uuid')).toBe(
+      `${attachmentUrl}?patient=patient-uuid&encounter=encounter-uuid`,
+    );
+  });
+});
+
+describe('getAttachments', () => {
+  beforeEach(() => {
+    mockOpenmrsFetch.mockReset();
+  });
+
+  it('requests the patient attachments', () => {
+    const abortController = new AbortController();
+    getAttachments('patient-uuid', true, abortController);
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(`${attachmentUrl}?patient=patient-uuid&includeEncounterless=true`, {
+      signal: abortController.signal,
+    });
+  });
+
+  it('requests only the attachments on an encounter when one is given', () => {
+    const abortController = new AbortController();
+    getAttachments('patient-uuid', true, abortController, 'encounter-uuid');
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(`${attachmentUrl}?patient=patient-uuid&encounter=encounter-uuid`, {
+      signal: abortController.signal,
+    });
+  });
+});
+
+describe('createAttachment', () => {
+  const file = new File(['content'], 'photo.png', { type: 'image/png' });
+
+  beforeEach(() => {
+    mockOpenmrsFetch.mockReset();
+  });
+
+  function submittedFormData(): FormData {
+    const [, options] = mockOpenmrsFetch.mock.calls[0];
+    return options.body as FormData;
+  }
+
+  it('posts the file, caption and patient', async () => {
+    await createAttachment('patient-uuid', {
+      file,
+      base64Content: '',
+      fileName: 'photo.png',
+      fileType: 'image/png',
+      fileDescription: 'Wound photo',
+    });
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(attachmentUrl, expect.objectContaining({ method: 'POST' }));
+    const formData = submittedFormData();
+    expect(formData.get('patient')).toBe('patient-uuid');
+    expect(formData.get('fileCaption')).toBe('Wound photo');
+    expect(formData.get('file')).toBeInstanceOf(File);
+    expect(formData.has('encounter')).toBe(false);
+    expect(formData.has('base64Content')).toBe(false);
+  });
+
+  it('records the attachment on the encounter when one is given', async () => {
+    await createAttachment(
+      'patient-uuid',
+      { file, base64Content: '', fileName: 'photo.png', fileType: 'image/png', fileDescription: 'Wound photo' },
+      'encounter-uuid',
+    );
+
+    expect(submittedFormData().get('encounter')).toBe('encounter-uuid');
+  });
+
+  it('sends base64 content with a placeholder file when no File is given', async () => {
+    await createAttachment('patient-uuid', {
+      base64Content: 'data:image/png;base64,AAAA',
+      fileName: 'capture.png',
+      fileType: 'image/png',
+      fileDescription: 'Webcam capture',
+    });
+
+    const formData = submittedFormData();
+    expect(formData.get('base64Content')).toBe('data:image/png;base64,AAAA');
+    expect((formData.get('file') as File).name).toBe('capture.png');
+  });
+});

package/src/attachments.ts

@@ -27,12 +27,17 @@ export function getAttachmentByUuid(attachmentUuid: string, abortController: Abo
 }
 
 /**
- * Fetches all attachments for a specific patient from the OpenMRS server.
+ * Fetches attachments for a specific patient from the OpenMRS server.
  *
  * @param patientUuid The UUID of the patient whose attachments should be fetched.
  * @param includeEncounterless Whether to include attachments that are not associated
- *   with any encounter.
+ *   with any encounter. Ignored when `encounterUuid` is set.
  * @param abortController An AbortController to allow cancellation of the request.
+ * @param encounterUuid When set, only attachments recorded on this encounter are returned.
+ *   The `includeEncounterless` parameter is not sent in that case, because the server
+ *   ignores the encounter filter whenever `includeEncounterless` is present. Pass a UUID
+ *   the server can resolve: an unknown encounter UUID makes the server fall back to every
+ *   attachment of the patient, encounterless ones included.
  * @returns A Promise that resolves with the FetchResponse containing an array of attachments.
  *
  * @example
@@ -41,14 +46,37 @@ export function getAttachmentByUuid(attachmentUuid: string, abortController: Abo
  * const abortController = new AbortController();
  * const response = await getAttachments('patient-uuid', true, abortController);
  * console.log(response.data.results);
+ *
+ * const forEncounter = await getAttachments('patient-uuid', false, abortController, 'encounter-uuid');
  * ```
  */
-export function getAttachments(patientUuid: string, includeEncounterless: boolean, abortController: AbortController) {
-  return openmrsFetch(`${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`, {
+export function getAttachments(
+  patientUuid: string,
+  includeEncounterless: boolean,
+  abortController: AbortController,
+  encounterUuid?: string,
+) {
+  return openmrsFetch(getAttachmentsUrl(patientUuid, includeEncounterless, encounterUuid), {
     signal: abortController.signal,
   });
 }
 
+/**
+ * Builds the attachment search URL for a patient. Used by `getAttachments` and `useAttachments`
+ * so both request (and cache under) the same key.
+ *
+ * @param patientUuid The UUID of the patient whose attachments should be fetched.
+ * @param includeEncounterless Whether to include attachments that are not associated
+ *   with any encounter. Ignored when `encounterUuid` is set.
+ * @param encounterUuid When set, restricts the search to attachments on this encounter.
+ */
+export function getAttachmentsUrl(patientUuid: string, includeEncounterless: boolean, encounterUuid?: string) {
+  if (encounterUuid) {
+    return `${attachmentUrl}?patient=${patientUuid}&encounter=${encounterUuid}`;
+  }
+  return `${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`;
+}
+
 /**
  * Creates a new attachment for a patient by uploading a file to the OpenMRS server.
  * The file can be provided either as a File object or as base64-encoded content.
@@ -57,6 +85,8 @@ export function getAttachments(patientUuid: string, includeEncounterless: boolea
  * @param fileToUpload An object containing the file data and metadata to upload.
  *   Should include `file` (File object) or `base64Content`, plus `fileName` and
  *   `fileDescription`.
+ * @param encounterUuid Optional UUID of an existing encounter to record the attachment on.
+ *   When omitted the attachment is saved without an encounter.
  * @returns A Promise that resolves with the FetchResponse containing the created
  *   attachment data.
  *
@@ -68,14 +98,21 @@ export function getAttachments(patientUuid: string, includeEncounterless: boolea
  *   fileName: 'document.pdf',
  *   fileDescription: 'Patient consent form'
  * });
+ *
+ * // Record the attachment on a specific encounter
+ * await createAttachment('patient-uuid', uploadedFile, 'encounter-uuid');
  * ```
  */
-export async function createAttachment(patientUuid: string, fileToUpload: UploadedFile) {
+export async function createAttachment(patientUuid: string, fileToUpload: UploadedFile, encounterUuid?: string) {
   const formData = new FormData();
 
   formData.append('fileCaption', fileToUpload.fileDescription);
   formData.append('patient', patientUuid);
 
+  if (encounterUuid) {
+    formData.append('encounter', encounterUuid);
+  }
+
   if (fileToUpload.file) {
     formData.append('file', fileToUpload.file, fileToUpload.fileName);
   } else {