#327: Fixed the issue with the absence of the File class in Node.js…

… v18.x.x by using `File` from `formdata-node`.

- Enhanced documentation with TSDoc and examples for better clarity.

package.json

@@ -64,7 +64,7 @@
     "eslint-import-resolver-typescript": "^3.7.0",
     "eslint-plugin-import": "^2.31.0",
     "prettier": "^3.4.2",
-    "prettier-plugin-jsdoc": "^1.3.0",
+    "prettier-plugin-jsdoc": "^1.3.2",
     "sinon": "^18.0.1",
     "typedoc": "^0.27.6",
     "typescript": "^5.7.2",

src/serviceDesk/parameters/attachTemporaryFile.ts

@@ -1,14 +1,103 @@
+/**
+ * Represents an attachment to be temporarily attached to a Service Desk.
+ *
+ * @example
+ *   ```typescript
+ *   const attachment: Attachment = {
+ *     filename: 'example.txt',
+ *     file: Buffer.from('Temporary file content'),
+ *     mimeType: 'text/plain',
+ *   };
+ *   ```
+ */
 export interface Attachment {
+  /**
+   * The name of the attachment file.
+   *
+   * @example
+   *   ```typescript
+   *   const filename = 'example.png';
+   *   ```
+   */
   filename: string;
+
+  /**
+   * The content of the attachment. Can be one of the following:
+   *
+   * - `Buffer`: For binary data.
+   * - `ReadableStream`: For streaming large files.
+   * - `string`: For text-based content.
+   * - `Blob`: For browser-like blob objects.
+   * - `File`: For file objects with metadata (e.g., in web environments).
+   *
+   * @example
+   *   ```typescript
+   *   const fileContent = Buffer.from('Example content here');
+   *   ```
+   */
   file: Buffer | ReadableStream | string | Blob | File;
+
+  /**
+   * Optional MIME type of the attachment. Example values include:
+   *
+   * - 'application/pdf'
+   * - 'image/jpeg' If not provided, the MIME type will be automatically detected based on the filename.
+   *
+   * @example
+   *   ```typescript
+   *   const mimeType = 'image/jpeg';
+   *   ```
+   */
   mimeType?: string;
 }
 
+/**
+ * Parameters for attaching temporary files to a Service Desk.
+ *
+ * @example
+ *   ```typescript
+ *   const attachTemporaryFileParams: AttachTemporaryFile = {
+ *     serviceDeskId: '5',
+ *     attachment: [
+ *       {
+ *         filename: 'example.txt',
+ *         file: Buffer.from('Temporary file content'),
+ *         mimeType: 'text/plain',
+ *       },
+ *     ],
+ *   };
+ *   ```
+ */
 export interface AttachTemporaryFile {
   /**
    * The ID of the Service Desk to which the file will be attached. This can alternatively be a [project
-   * identifier.](#project-identifiers)
+   * identifier](#project-identifiers).
+   *
+   * @example
+   *   ```typescript
+   *   const serviceDeskId = '5';
+   *   ```
    */
   serviceDeskId: string;
+
+  /**
+   * The attachment(s) to be added. Can be a single `Attachment` object or an array of `Attachment` objects.
+   *
+   * @example
+   *   ```typescript
+   *   const attachments = [
+   *     {
+   *       filename: 'file1.txt',
+   *       file: Buffer.from('Temporary content 1'),
+   *       mimeType: 'text/plain',
+   *     },
+   *     {
+   *       filename: 'file2.jpeg',
+   *       file: Buffer.from('Temporary content 2'),
+   *       mimeType: 'image/jpeg',
+   *     },
+   *   ];
+   *   ```
+   */
   attachment: Attachment | Attachment[];
 }

src/serviceDesk/serviceDesk.ts

@@ -1,4 +1,4 @@
-import { FormData } from 'formdata-node';
+import { FormData, File } from 'formdata-node';
 import * as mime from 'mime-types';
 import * as Models from './models';
 import * as Parameters from './parameters';

src/version2/issueAttachments.ts

@@ -1,4 +1,4 @@
-import { FormData } from 'formdata-node';
+import { FormData, File } from 'formdata-node';
 import * as mime from 'mime-types';
 import * as Models from './models';
 import * as Parameters from './parameters';

src/version2/parameters/addAttachment.ts

@@ -1,12 +1,101 @@
+/**
+ * Represents an attachment to be added to an issue.
+ *
+ * @example
+ *   ```typescript
+ *     const attachment: Attachment = {
+ *       filename: 'example.txt',
+ *       file: Buffer.from('Hello, world!'),
+ *       mimeType: 'text/plain',
+ *     };
+ *   ```
+ */
 export interface Attachment {
+  /**
+   * The name of the attachment file.
+   *
+   * @example
+   *   ```typescript
+   *   const filename = 'document.pdf';
+   *   ```
+   */
   filename: string;
+
+  /**
+   * The content of the attachment. Can be one of the following:
+   *
+   * - `Buffer`: For binary data.
+   * - `ReadableStream`: For streaming large files.
+   * - `string`: For text-based content.
+   * - `Blob`: For browser-like blob objects.
+   * - `File`: For file objects with metadata (e.g., in web environments).
+   *
+   * @example
+   *   ```typescript
+   *   const fileContent = fs.readFileSync('./document.pdf');
+   *   ```
+   */
   file: Buffer | ReadableStream | string | Blob | File;
+
+  /**
+   * Optional MIME type of the attachment. Example values include:
+   *
+   * - 'application/pdf'
+   * - 'image/png'
+   *
+   * If not provided, the MIME type will be automatically detected based on the filename.
+   *
+   * @example
+   *   ```typescript
+   *   const mimeType = 'application/pdf';
+   *   ```
+   */
   mimeType?: string;
 }
 
+/**
+ * Parameters for adding attachments to an issue.
+ *
+ * @example
+ *   ```typescript
+ *   const addAttachmentParams: AddAttachment = {
+ *     issueIdOrKey: 'PROJECT-123',
+ *     attachment: {
+ *       filename: 'example.txt',
+ *       file: 'Hello, world!',
+ *       mimeType: 'text/plain',
+ *     },
+ *   };
+ *   ```
+ */
 export interface AddAttachment {
-  /** The ID or key of the issue that attachments are added to. */
+  /**
+   * The ID or key of the issue to which the attachments will be added.
+   *
+   * @example
+   *   ```typescript
+   *   const issueIdOrKey = 'PROJECT-123';
+   *   ```
+   */
   issueIdOrKey: string;
 
+  /**
+   * The attachment(s) to be added. Can be a single `Attachment` object or an array of `Attachment` objects.
+   *
+   * @example
+   *   ```typescript
+   *   const attachments = [
+   *     {
+   *       filename: 'file1.txt',
+   *       file: Buffer.from('File 1 content'),
+   *       mimeType: 'text/plain',
+   *     },
+   *     {
+   *       filename: 'proof image.png',
+   *       file: fs.readFileSync('./image.png'), // Reads the image file into a Buffer
+   *     },
+   *   ];
+   *   ```
+   */
   attachment: Attachment | Attachment[];
 }

src/version3/issueAttachments.ts

@@ -1,4 +1,4 @@
-import { FormData } from 'formdata-node';
+import { FormData, File } from 'formdata-node';
 import * as mime from 'mime-types';
 import * as Models from './models';
 import * as Parameters from './parameters';

src/version3/parameters/addAttachment.ts

@@ -1,12 +1,101 @@
+/**
+ * Represents an attachment to be added to an issue.
+ *
+ * @example
+ *   ```typescript
+ *   const attachment: Attachment = {
+ *     filename: 'example.txt',
+ *     file: Buffer.from('Hello, world!'),
+ *     mimeType: 'text/plain',
+ *   };
+ *   ```
+ */
 export interface Attachment {
+  /**
+   * The name of the attachment file.
+   *
+   * @example
+   *   ```typescript
+   *   const filename = 'document.pdf';
+   *   ```
+   */
   filename: string;
+
+  /**
+   * The content of the attachment. Can be one of the following:
+   *
+   * - `Buffer`: For binary data.
+   * - `ReadableStream`: For streaming large files.
+   * - `string`: For text-based content.
+   * - `Blob`: For browser-like blob objects.
+   * - `File`: For file objects with metadata (e.g., in web environments).
+   *
+   * @example
+   *   ```typescript
+   *   const fileContent = fs.readFileSync('./document.pdf');
+   *   ```
+   */
   file: Buffer | ReadableStream | string | Blob | File;
+
+  /**
+   * Optional MIME type of the attachment. Example values include:
+   *
+   * - 'application/pdf'
+   * - 'image/png'
+   *
+   * If not provided, the MIME type will be automatically detected based on the filename.
+   *
+   * @example
+   *   ```typescript
+   *   const mimeType = 'application/pdf';
+   *   ```
+   */
   mimeType?: string;
 }
 
+/**
+ * Parameters for adding attachments to an issue.
+ *
+ * @example
+ *   ```typescript
+ *   const addAttachmentParams: AddAttachment = {
+ *     issueIdOrKey: 'PROJECT-123',
+ *     attachment: {
+ *       filename: 'example.txt',
+ *       file: 'Hello, world!',
+ *       mimeType: 'text/plain',
+ *     },
+ *   };
+ *   ```
+ */
 export interface AddAttachment {
-  /** The ID or key of the issue that attachments are added to. */
+  /**
+   * The ID or key of the issue to which the attachments will be added.
+   *
+   * @example
+   *   ```typescript
+   *   const issueIdOrKey = 'PROJECT-123';
+   *   ```
+   */
   issueIdOrKey: string;
 
+  /**
+   * The attachment(s) to be added. Can be a single `Attachment` object or an array of `Attachment` objects.
+   *
+   * @example
+   *   ```typescript
+   *   const attachments = [
+   *     {
+   *       filename: 'file1.txt',
+   *       file: Buffer.from('File 1 content'),
+   *       mimeType: 'text/plain',
+   *     },
+   *     {
+   *       filename: 'proof image.png',
+   *       file: fs.readFileSync('./image.png'), // Reads the image file into a Buffer
+   *     },
+   *   ];
+   *   ```
+   */
   attachment: Attachment | Attachment[];
 }

tests/integration/version2/issueAttachments.test.ts

@@ -45,12 +45,29 @@ test.sequential('should add attachment', async ({ expect }) => {
   expect(attachments[0].mimeType).toBe('video/mp2t');
 });
 
+test.sequential('should add attachment with custom MIME type', async ({ expect }) => {
+  const customMimeType = 'application/typescript';
+
+  const customAttachment = await client.issueAttachments.addAttachment({
+    issueIdOrKey: issue.key,
+    attachment: {
+      filename: 'issueAttachments.test.ts',
+      file: fs.readFileSync('./tests/integration/version2/issueAttachments.test.ts'),
+      mimeType: customMimeType,
+    },
+  });
+
+  expect(!!customAttachment).toBeTruthy();
+  expect(customAttachment[0].filename).toBe('issueAttachments.test.ts');
+  expect(customAttachment[0].mimeType).toBe(customMimeType);
+});
+
 test.sequential('should getAttachmentContent', async ({ expect }) => {
   const content = await client.issueAttachments.getAttachmentContent({ id: attachments[0].id });
 
   expect(Buffer.isBuffer(content)).toBeTruthy();
 });
 
-test.sequential('should remove attachment', async ({ expect }) => {
+test.sequential('should remove attachment', async () => {
   await client.issues.deleteIssue({ issueIdOrKey: issue.key });
 });

tests/integration/version3/issueAttachments.test.ts

@@ -45,12 +45,29 @@ test.sequential('should add attachment', async ({ expect }) => {
   expect(attachments[0].mimeType).toBe('video/mp2t');
 });
 
+test.sequential('should add attachment with custom MIME type', async ({ expect }) => {
+  const customMimeType = 'application/typescript';
+
+  const customAttachment = await client.issueAttachments.addAttachment({
+    issueIdOrKey: issue.key,
+    attachment: {
+      filename: 'issueAttachments.test.ts',
+      file: fs.readFileSync('./tests/integration/version2/issueAttachments.test.ts'),
+      mimeType: customMimeType,
+    },
+  });
+
+  expect(!!customAttachment).toBeTruthy();
+  expect(customAttachment[0].filename).toBe('issueAttachments.test.ts');
+  expect(customAttachment[0].mimeType).toBe(customMimeType);
+});
+
 test.sequential('should getAttachmentContent', async ({ expect }) => {
   const content = await client.issueAttachments.getAttachmentContent({ id: attachments[0].id });
 
   expect(Buffer.isBuffer(content)).toBeTruthy();
 });
 
-test.sequential('should remove attachment', async ({ expect }) => {
+test.sequential('should remove attachment', async () => {
   await client.issues.deleteIssue({ issueIdOrKey: issue.key });
 });