chore: upgrade typedoc and fix all warnings

Author: blakmatrix

examples/create-oauth-token.js

@@ -24,7 +24,6 @@ const setupClient = (config) => {
  * Retrieves the numeric ID of an OAuth client based on its unique identifier.
  * @param {string} identifier - The unique identifier of the OAuth client.
  * @returns {Promise<number|null>} The numeric ID of the OAuth client or null if not found.
- * @async
  * @throws {Error} If there's an error in retrieving the OAuth client list.
  */
 async function getClientId(identifier) {
@@ -43,7 +42,6 @@ async function getClientId(identifier) {
  * Creates a read-only OAuth token for accessing users and tickets.
  * This function first retrieves the OAuth client ID using its unique identifier,
  * and then uses this ID to create a token with the specified scopes.
- * @async
  * @throws {Error} If the OAuth client ID is not found or if there's an error in creating the OAuth token.
  */
 async function createReadOnlyOAuthToken() {

package.json

@@ -155,8 +155,8 @@
     "dotenv": "^16.4.0",
     "eslint-plugin-jsdoc": "^48.0.2",
     "nock": "^13.5.0",
-    "typedoc": "^0.25.7",
-    "typedoc-plugin-markdown": "^3.17.1",
+    "typedoc": "^0.26.5",
+    "typedoc-plugin-markdown": "^4.2.3",
     "vitepress": "1.3.1",
     "vitepress-sidebar": "1.24.1",
     "vitest": "^1.2.1",

src/clients/client.js

@@ -12,19 +12,14 @@ const {
 } = require('./helpers');
 
 /**
- * @typedef {object} ClientOptions
- * @property {string} subdomain - Subdomain for the Zendesk instance.
- * @property {string} [password] - Password for authentication.
- * @property {string} [token] - Token for authentication.
- * @property {boolean} [useOAuth] - Flag to indicate if OAuth is used.
- * @property {string} [username] - Username for authentication.
- * @property {string} [asUser] - Optional header for making requests on behalf of a user.
- * @property {object} [customHeaders] - Any additional custom headers for the request.
- * @property {boolean} [throttle] - Flag to enable throttling of requests.
- * @property {boolean} [throwOriginalException] - Throw the original exception when API requests fail.
- * @property {CustomEventTarget} eventTarget - Event target to handle custom events.
- * @property {Array} sideLoad - Array to handle side-loaded resources.
- * @property {Array} jsonAPINames - Array to hold names used in the JSON API.
+ * @typedef {import('../index').ZendeskClientOptions} ZendeskClientOptions
+ */
+
+/**
+ * @typedef {ZendeskClientOptions} ClientOptions
+ *
+ * This type extends `ZendeskClientOptions` to be used for configuring the Client instance.
+ * All properties of `ZendeskClientOptions` are available here.
  */
 
 /**
@@ -33,7 +28,6 @@ const {
  * @class
  * @property {ClientOptions} options - Configuration options for the client.
  * @property {Array} sideLoad - Array to handle side-loaded resources.
- * @property {string} userAgent - User agent for the client.
  * @property {Array} jsonAPINames - Array to hold names used in the JSON API.
  * @property {boolean} useDotJson - Flag to indicate if the API endpoint should use '.json' ending.
  * @property {ApiTypes} apiType - Type of Zendesk API to initialize (e.g., 'core', 'helpcenter').
@@ -42,7 +36,6 @@ const {
  */
 class Client {
   /**
-   * @constructs Client
    * @param {ClientOptions} options - Configuration options for the client.
    * @param {ApiTypes} apiType - Type of Zendesk API to initialize (e.g., 'core', 'helpcenter').
    */

src/clients/core/accountsettings.js

@@ -5,7 +5,6 @@ const {Client} = require('../client');
 /**
  * The AccountSettings class provides methods for interacting with account settings in the Zendesk JSON API.
  * {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/account_settings/ | See the Zendesk API documentation for more details}.
- * @augments Client
  */
 class AccountSettings extends Client {
   constructor(options) {
@@ -17,7 +16,6 @@ class AccountSettings extends Client {
    * Retrieves the account settings.
    * @returns {Promise<object>} A promise that resolves to the account settings.
    * {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/account_settings/#show-settings | See the Zendesk API documentation for more details}.
-   * @async
    * @example
    * const settings = await client.accountsettings.show();
    */
@@ -30,7 +28,6 @@ class AccountSettings extends Client {
    * @param {object} settings - The settings to update.
    * @returns {Promise<object>} A promise that resolves to the updated account settings.
    * {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/account_settings/#update-account-settings | See the Zendesk API documentation for more details}.
-   * @async
    * @example
    * const settings = await client.accountsettings.update({ "settings": { "active_features": { "customer_satisfaction": false }}});
    */

src/clients/core/activitystream.js

@@ -5,8 +5,6 @@ const {Client} = require('../client');
 /**
  * `ActivityStream` provides methods to interact with Zendesk ticket activities.
  * This class extends the base Client class and is tailored to fetch activity data.
- * @class
- * @augments {Client}
  * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/activity_stream/ | Zendesk Activity Stream API}
  * @example
  * const client = new Client({ /* ...options... * / });
@@ -25,7 +23,6 @@ class ActivityStream extends Client {
   /**
    * Lists all ticket activities from the Zendesk API.
    * @returns {Array<object>} An array of activity objects.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/activity_stream/#list-activities | Zendesk API - List Activities}
    * @example
    * const activities = await client.activitystream.list();
@@ -38,7 +35,6 @@ class ActivityStream extends Client {
    * Retrieves a specific ticket activity by its ID.
    * @param {number} activityID - The unique ID of the activity to fetch.
    * @returns {Promise<object>} A promise that resolves to the activity object corresponding to the provided activityID.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/activity_stream/#show-activity | Zendesk API - Show Activity}
    * @example
    * const activity = await client.activitystream.show(12345);  // Where 12345 is an activity ID.
@@ -55,7 +51,6 @@ class ActivityStream extends Client {
    * Note: When the count exceeds 100,000, count[refreshed_at] may occasionally be null. This indicates
    * that the count is being updated in the background, and count[value] is limited to 100,000 until the update is complete.
    * @returns {Promise<object>} A promise that resolves to an object containing the activity count and the refreshed_at timestamp.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/activity_stream/#count-activities | Zendesk API - Count Activities}
    * @example
    * const activityCount = await client.activitystream.count();

src/clients/core/attachments.js

@@ -3,7 +3,6 @@ const {Client} = require('../client');
 
 /**
  * Represents the Attachments functionality of the Zendesk API.
- * @augments {Client}
  * @see [Zendesk Attachments API]{@link https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/}
  */
 class Attachments extends Client {
@@ -19,7 +18,6 @@ class Attachments extends Client {
    * @param {boolean} fileOptions.binary - If the file is binary or not.
    * @param {string} [fileOptions.token] - Token received from previous uploads (if multiple files are being attached).
    * @returns {Promise<object>} Returns the server's response.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/#upload-files}
    * @example
    * const response = await client.attachments.upload(fileBuffer, { filename: "example.png", binary: true });
@@ -49,7 +47,6 @@ class Attachments extends Client {
    * Delete an uploaded file.
    * @param {string} token - The token of the uploaded attachment.
    * @returns {Promise<object>} Returns the server's response.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/#delete-upload}
    * @example
    * const response = await client.attachments.deleteUpload("exampleToken");
@@ -62,7 +59,6 @@ class Attachments extends Client {
    * Retrieve details of a specific attachment.
    * @param {number} attachmentID - The ID of the attachment.
    * @returns {Promise<object>} Returns the details of the attachment.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/#show-attachment}
    * @example
    * const attachmentDetails = await client.attachments.show(12345);
@@ -77,7 +73,6 @@ class Attachments extends Client {
    * @param {number} commentID - The ID of the comment.
    * @param {number} attachmentID - The ID of the attachment.
    * @returns {Promise<object>} Returns the server's response.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/#redact-comment-attachment}
    * @example
    * const response = await client.attachments.redactAttachmentComment(1, 2, 3);
@@ -102,7 +97,6 @@ class Attachments extends Client {
    * @param {number} attachmentID - The ID of the attachment.
    * @param {boolean} malwareAccessOverride - Whether to override malware access. If true, agent can access attachment flagged as malware.
    * @returns {Promise<object>} The response from the Zendesk API.
-   * @async
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/#update-attachment-for-malware}
    * @example

src/clients/core/automations.js

@@ -8,7 +8,6 @@ const {Client} = require('../client');
 /**
  * The Automations class provides methods for interacting with the Zendesk Automation API.
  * {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/| See the Zendesk API documentation for more details}.
- * @augments Client
  */
 class Automations extends Client {
   constructor(options) {
@@ -19,7 +18,6 @@ class Automations extends Client {
   /**
    * List all automations.
    * @returns {Promise<Array>} Returns a list of automations.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#list-automations}
    * @example const automations = await client.automations.list();
    */
@@ -30,7 +28,6 @@ class Automations extends Client {
   /**
    * List all active automations.
    * @returns {Promise<Array>} Returns a list of active automations.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#list-active-automations}
    * @example const activeAutomations = await client.automations.listActive();
    */
@@ -42,7 +39,6 @@ class Automations extends Client {
    * Get details of a specific automation by ID.
    * @param {number} automationID - The ID of the automation.
    * @returns {Promise<object>} Returns details of the automation.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#show-automation}
    * @example const automationDetails = await client.automations.show(123456);
    */
@@ -54,7 +50,6 @@ class Automations extends Client {
    * Create a new automation.
    * @param {object} automationData - Data for the new automation.
    * @returns {Promise<object>} Returns the created automation.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#create-automation}
    * @example
    * const automation = await client.automations.create({
@@ -72,7 +67,6 @@ class Automations extends Client {
    * @param {number} automationID - ID of the automation to update.
    * @param {object} updatedData - Updated data for the automation.
    * @returns {Promise<object>} Returns the updated automation.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#update-automation}
    * @example
    * const updatedAutomation = await client.automations.update(12345, {
@@ -87,7 +81,6 @@ class Automations extends Client {
    * Update many automations in bulk.
    * @param {Array<object>} automations - Array of automation data with their IDs to be updated.
    * @returns {Promise<object>} Returns the status of the bulk update.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#update-many-automation}
    * @example
    * const status = await client.automations.updateMany([{id: 123, position: 1}, {id: 124, position: 2}]);
@@ -100,7 +93,6 @@ class Automations extends Client {
    * Delete an automation.
    * @param {number} automationID - ID of the automation to be deleted.
    * @returns {Promise<void>}
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#delete-automation}
    * @example
    * await client.automations.delete(12345);
@@ -113,7 +105,6 @@ class Automations extends Client {
    * Bulk delete automations.
    * @param {Array<number>} ids - Array of automation IDs to be deleted.
    * @returns {Promise<void>}
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#bulk-delete-automation}
    * @example
    * await client.automations.bulkDelete([12345, 67890]);
@@ -126,7 +117,6 @@ class Automations extends Client {
    * Search automations by with query.
    * @param {object} searchQuery - The parameters to search for ['active', 'include', 'query', 'sort_by', 'sort_order'].
    * @returns {Promise<Array>} Returns automations matching the search query.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#search-automation}
    * @example const foundAutomations = await client.automations.search('close');
    */
@@ -138,7 +128,6 @@ class Automations extends Client {
    * Reorder the list of automations.
    * @param {Array<number>} automationIDs - Array of automation IDs in the desired order.
    * @returns {Promise<object>} Returns the status of the reorder.
-   * @async
    * @example
    * const status = await client.automations.reorder([67890, 12345]);
    * @deprecated This may now be deprecated, please notify developers if you find this to be the case.

src/clients/core/brand.js

@@ -13,7 +13,6 @@ class Brand extends Client {
   /**
    * List all brands.
    * @returns {Promise<object>} The list of brands.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#list-brands}
    * @example const brands = await client.brands.list();
    */
@@ -25,7 +24,6 @@ class Brand extends Client {
    * Show a specific brand by ID.
    * @param {number} brandId - The ID of the brand.
    * @returns {Promise<object>} The brand details.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#show-a-brand}
    * @example const brand = await client.brands.show(47);
    */
@@ -37,7 +35,6 @@ class Brand extends Client {
    * Create a new brand.
    * @param {object} brand - The brand data.
    * @returns {Promise<object>} The created brand details.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#create-brand}
    * @example const newBrand = await client.brands.create({name: "Brand 1", subdomain: "Brand1"});
    */
@@ -50,7 +47,6 @@ class Brand extends Client {
    * @param {object} brand - The updated brand data.
    * @param {number} brandId - The ID of the brand to update.
    * @returns {Promise<object>} The updated brand details.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#update-a-brand}
    * @example const updatedBrand = await client.brands.update({name: "Updated Brand"}, 47);
    */
@@ -62,7 +58,6 @@ class Brand extends Client {
    * Delete a brand.
    * @param {number} brandId - The ID of the brand to delete.
    * @returns {Promise<object>} The deletion status.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#delete-a-brand}
    * @example await client.brands.delete(47);
    */
@@ -75,7 +70,6 @@ class Brand extends Client {
    * @param {string} hostMapping - The host mapping to check.
    * @param {string} subdomain - The subdomain to check.
    * @returns {Promise<object>} The check result.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#check-host-mapping-validity}
    * @example await client.brands.checkHostMapping("brand1.com", "brand1");
    */
@@ -91,7 +85,6 @@ class Brand extends Client {
    * Check host mapping validity for an existing brand.
    * @param {number} brandId - The ID of the brand to check.
    * @returns {Promise<object>} The check result.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#check-host-mapping-validity-for-an-existing-brand}
    * @example await client.brands.checkHostMappingForExistingBrand(47);
    */

src/clients/core/customagentroles.js

@@ -2,8 +2,7 @@
 const {Client} = require('../client');
 
 /**
- * @class
- * @classdesc Client for Zendesk's Custom Agent Roles API.
+ * Client for Zendesk's Custom Agent Roles API.
  * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/}
  */
 class CustomAgentRoles extends Client {
@@ -15,7 +14,6 @@ class CustomAgentRoles extends Client {
   /**
    * List all Custom Agent Roles.
    * @returns {Promise<object[]>} Returns a promise that resolves with the list of custom agent roles.
-   * @async
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#list-custom-roles}
    * @example
    * const client = createClient({...});
@@ -29,7 +27,6 @@ class CustomAgentRoles extends Client {
    * Retrieve a specific Custom Agent Role by its ID.
    * @param {number} roleId The ID of the custom agent role to retrieve.
    * @returns {Promise<object>} Returns a promise that resolves with the specified custom agent role.
-   * @async
    * @throws Will throw an error if unable to retrieve the role.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#show-custom-role}
    * @example
@@ -44,7 +41,6 @@ class CustomAgentRoles extends Client {
    * Creates a new custom agent role.
    * @param {object} roleData - The data for the new custom agent role.
    * @returns {Promise<object>} The created custom agent role.
-   * @async
    * @throws Will throw an error if creation fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#create-custom-role}
    * @example
@@ -64,7 +60,6 @@ class CustomAgentRoles extends Client {
    * @param {number} customRoleId - The ID of the custom agent role to update.
    * @param {object} updatedData - The updated data for the custom agent role.
    * @returns {Promise<object>} The updated custom agent role.
-   * @async
    * @throws Will throw an error if the update fails or custom agent role ID is not found.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#update-custom-role}
    * @example
@@ -79,7 +74,6 @@ class CustomAgentRoles extends Client {
    * Delete a specific Custom Agent Role by its ID.
    * @param {number} roleId The ID of the custom agent role to delete.
    * @returns {Promise<void>} Returns a promise that resolves when the role is deleted.
-   * @async
    * @throws Will throw an error if unable to delete the role.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#delete-custom-role}
    * @example