Merge branch 'master' into master

Author: blakmatrix

examples/organization-upsert.js

@@ -16,10 +16,13 @@ const organization = {
   },
 };
 
-client.organizations.upsert(organization, function (error, request, result) {
-  if (error) return handleError(error);
-  console.log(JSON.stringify(result, null, 2, true));
-});
+client.organizations.createOrUpdate(
+  {organization},
+  function (error, request, result) {
+    if (error) return handleError(error);
+    console.log(JSON.stringify(result, null, 2, true));
+  },
+);
 
 /**
  * Handles errors by logging them and exiting the process.

package-lock.json

@@ -1,18 +1,45 @@
 // File: brands.js
 const {Client} = require('../client');
+
+/**
+ * Brands are your customer-facing identities.
+ * @typedef {object} Brand
+ * @property {boolean} [active] - If the brand is set as active
+ * @property {string} [brand_url] - The url of the brand
+ * @property {string} created_at - The time the brand was created
+ * @property {boolean} [default] - Is the brand the default brand for this account
+ * @property {boolean} [has_help_center] - If the brand has a Help Center
+ * @property {'enabled' | 'disabled' | 'restricted'} help_center_state - The state of the Help Center
+ * @property {string | null} [host_mapping] - The hostmapping to this brand, if any. Only admins view this property
+ * @property {number} id - The ID automatically assigned when the brand is created
+ * @property {boolean} [is_deleted] - If the brand object is deleted or not
+ * @property {object | null} [logo] - A file represented as an Attachment object
+ * @property {string} name - The name of the brand
+ * @property {string} [signature_template] - The signature template for a brand
+ * @property {string} subdomain - The subdomain of the brand
+ * @property {number[]} [ticket_form_ids] - The ids of ticket forms that are available for use by a brand
+ * @property {string} [updated_at] - The time of the last update of the brand
+ * @property {string} [url] - The API url of this brand
+ */
+
+/**
+ * @typedef {object} CreateOrUpdateBrand
+ * @property {Partial<Brand>} brand - The brand object to create or update.
+ */
+
 /**
  * Class representing the Brand API endpoints.
  * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/}
  */
-class Brand extends Client {
+class Brands extends Client {
   constructor(options) {
     super(options);
     this.jsonAPINames = ['brands'];
   }
 
   /**
    * List all brands.
-   * @returns {Promise<{response: object, result: Array<object>}>} The list of brands.
+   * @returns {Promise<{response: object, result: Array<Brand>}>} The list of brands.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#list-brands}
    * @example const brands = await client.brands.list();
    */
@@ -23,7 +50,7 @@ class Brand extends Client {
   /**
    * Show a specific brand by ID.
    * @param {number} brandId - The ID of the brand.
-   * @returns {Promise<{response: object, result: object}>} The brand details.
+   * @returns {Promise<{response: object, result: { brand: Brand }}>} The brand details.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#show-a-brand}
    * @example const brand = await client.brands.show(47);
    */
@@ -33,8 +60,8 @@ class Brand extends Client {
 
   /**
    * Create a new brand.
-   * @param {object} brand - The brand data.
-   * @returns {Promise<{response: object, result: object}>} The created brand details.
+   * @param {CreateOrUpdateBrand} brand - The brand data.
+   * @returns {Promise<{response: object, result: { brand: Brand }}>} The created brand details.
    * @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"});
    */
@@ -44,9 +71,9 @@ class Brand extends Client {
 
   /**
    * Update an existing brand.
-   * @param {object} brand - The updated brand data.
+   * @param {CreateOrUpdateBrand} brand - The updated brand data.
    * @param {number} brandId - The ID of the brand to update.
-   * @returns {Promise<{response: object, result: object}>} The updated brand details.
+   * @returns {Promise<{response: object, result: { brand: Brand }}>} The updated brand details.
    * @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);
    */
@@ -93,4 +120,4 @@ class Brand extends Client {
   }
 }
 
-exports.Brand = Brand;
+exports.Brands = Brands;

src/clients/core/brand.js

@@ -1,6 +1,33 @@
 // Macros.js: Client for the zendesk API.
 const {Client} = require('../client');
 
+/**
+ * A recursive type that makes all properties of an object optional, including nested objects.
+ * @template T
+ * @typedef {Partial<{[K in keyof T]: RecursivePartial<T[K]>}>} RecursivePartial
+ */
+
+/**
+ * A macro consists of one or more actions that modify the values of a ticket's fields
+ * @typedef {object} Macro
+ * @property {Array<object>} actions - Each action describes what the macro will do
+ * @property {boolean} [active] - Useful for determining if the macro should be displayed
+ * @property {string} [created_at] - The time the macro was created
+ * @property {boolean} [default] - If true, the macro is a default macro
+ * @property {string} [description] - The description of the macro
+ * @property {number} id - The id automatically assigned when a macro is created
+ * @property {number} [position] - The position of the macro
+ * @property {object} [restriction] - Access to this macro. A null value allows unrestricted access for all users in the account
+ * @property {string} title - The title of the macro
+ * @property {string} [updated_at] - The time of the last update of the macro
+ * @property {string} [url] - A URL to access the macro's details
+ */
+
+/**
+ * @typedef {object} CreateOrUpdateMacro
+ * @property {RecursivePartial<Macro>} macro - The macro object to create or update.
+ */
+
 /**
  * The Macros class provides methods for interacting with the Zendesk Macros API.
  * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/} Zendesk Macros API
@@ -13,7 +40,7 @@ class Macros extends Client {
 
   /**
    * Lists all shared and personal macros available to the current user.
-   * @returns {Promise<Array>} Returns a promise that resolves to an array of macros.
+   * @returns {Promise<Array<Macro>>} Returns a promise that resolves to an array of macros.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-macros} Zendesk List Macros API
    * @example
@@ -26,7 +53,7 @@ class Macros extends Client {
   /**
    * Retrieves details of a specific macro.
    * @param {number} macroID - The ID of the macro to retrieve.
-   * @returns {Promise<{response: object, result: object}>} Returns a promise that resolves to the macro's details.
+   * @returns {Promise<{response: object, result: { macro: Macro }}>} Returns a promise that resolves to the macro's details.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#show-macro} Zendesk Show Macro API
    * @example
@@ -51,7 +78,7 @@ class Macros extends Client {
 
   /**
    * Lists all active macros.
-   * @returns {Promise<{response: object, result: Array<object>}>} - A promise that resolves to a list of active macros.
+   * @returns {Promise<{response: object, result: Array<Macro[]>}>} - A promise that resolves to a list of active macros.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-active-macros}
    * @example
@@ -64,7 +91,7 @@ class Macros extends Client {
   /**
    * Lists macros based on provided parameters.
    * @param {object} parameters - The filtering parameters.
-   * @returns {Promise<object>} - A promise that resolves to a list of macros.
+   * @returns {Promise<Array<Macro>>} - A promise that resolves to a list of macros.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-macros}
    * @example
@@ -77,7 +104,7 @@ class Macros extends Client {
   /**
    * Applies a macro to a ticket.
    * @param {number} macroID - The ID of the macro.
-   * @returns {Promise<{response: object, result: object}>} - A promise that resolves to the applied macro's result.
+   * @returns {Promise<{response: object, result: { ticket: RecursivePartial<import('./tickets').Ticket> }}>} - A promise that resolves to the applied macro's result.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#show-macro-replica}
    * @example
@@ -91,7 +118,7 @@ class Macros extends Client {
    * Creates a macro representation derived from a ticket.
    * @param {number} ticketID - The ID of the ticket from which to build a macro replica.
    * @param {number} macroID - The ID of the macro.
-   * @returns {Promise<{response: object, result: object}>} - A promise that resolves to the macro replica.
+   * @returns {Promise<{response: object, result:  { ticket: RecursivePartial<import('./tickets').Ticket> }}>} - A promise that resolves to the macro replica.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#show-macro-replica}
    * @example
@@ -108,7 +135,7 @@ class Macros extends Client {
    * @param {string} macro.title - The title of the macro.
    * @param {boolean} [macro.active] - Whether the macro is active.
    * @param {string} [macro.description] - The description of the macro.
-   * @returns {Promise<{response: object, result: object}>} - A promise that resolves to the created macro.
+   * @returns {Promise<{response: object, result: { macro: Macro }}>} - A promise that resolves to the created macro.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#create-macro}
    * @example
@@ -123,7 +150,7 @@ class Macros extends Client {
 
   /**
    * Lists all macro categories available to the current user.
-   * @returns {Promise<object>} - A promise that resolves to a list of macro categories.
+   * @returns {Promise<Array<{ categories: Array<string> }>>} - A promise that resolves to a list of macro categories.
    * @throws {Error} Throws an error if the request fails.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-macro-categories}
    * @example