Better types for brands, tickets, macros, webhooks, articles

src/clients/core/brand.js

@@ -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/macros.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

src/clients/core/tickets.js

@@ -39,7 +39,7 @@ const {Client} = require('../client');
  * @property {boolean} public - true if a public comment; false if an internal note. The initial value set on ticket creation persists for any additional comment unless you change it
  * @property {string} type - Comment or VoiceComment. The JSON object for adding voice comments to tickets is different. See Adding voice comments to tickets
  * @property {string[]} [uploads] - List of tokens received from uploading files for comment attachments. The files are attached by creating or updating tickets with the tokens. See Attaching files in Tickets
- * @property {object} [via] - Describes how the object was created. See the Via object reference
+ * @property {Via} [via] - Describes how the object was created. See the Via object reference
  */
 
 /**
@@ -93,7 +93,7 @@ const {Client} = require('../client');
  * @property {string} updated_at - When this record last got updated
  * @property {string} [updated_stamp] - Write only. Datetime of last update received from API. See the safe_update property
  * @property {string} url - The API url of this ticket
- * @property {object} [via] - For more information, see the Via object reference
+ * @property {Via} [via] - For more information, see the Via object reference
  * @property {number} [via_followup_source_id] - POST requests only. The id of a closed ticket when creating a follow-up ticket. See Creating a follow-up ticket
  * @property {number} [via_id] - Write only. For more information, see the Via object reference
  * @property {object} [voice_comment] - Write only. See Creating voicemail ticket
@@ -127,6 +127,12 @@ const {Client} = require('../client');
  * @property {Array<Ticket>} [tickets] - The ticket object to create many tickets.
  */
 
+/**
+ * @typedef {object} Via
+ * @property {string} [channel] - How the ticket or event was created expressed as a via type or via id
+ * @property {object} source - For some channels a source object gives more information about how or why the ticket or event was created
+ */
+
 /**
  * @class
  * Client for the Zendesk API - Tickets.
@@ -523,7 +529,7 @@ class Tickets extends Client {
   /**
    * Retrieve comments associated with a specific ticket.
    * @param {number} ticketId - The ID of the ticket to retrieve comments for.
-   * @returns {Promise<Array>} A promise that resolves with an array of comments associated with the ticket.
+   * @returns {Promise<Array<TicketComment>>} A promise that resolves with an array of comments associated with the ticket.
    * @throws {Error} If `ticketId` is not a valid number.
    * @see {@link https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/}
    * @example

src/clients/core/webhooks.js

@@ -1,6 +1,38 @@
 // Webhooks.js: Client for the zendesk API.
 const {Client} = require('../client');
 
+/**
+ * A webhook sends an HTTP request to a specified URL in response to an activity in Zendesk Support.
+ * @typedef {object} Webhook
+ * @property {object} [authentication] - Adds authentication to the webhook's HTTP requests. See Webhook security and authentication
+ * @property {string} [created_at] - When the webhook was created (read-only)
+ * @property {string} [created_by] - id of the user who created the webhook. "-1" represents the Zendesk system (read-only)
+ * @property {object} [custom_headers] - Custom headers to deliver additional non-credential info to destinations
+ * @property {string} [description] - Webhook description
+ * @property {string} endpoint - The destination URL that the webhook notifies when Zendesk events occur
+ * @property {object} [external_source] - External source by which a webhook is created, e.g. Zendesk Marketplace
+ * @property {'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'} http_method - HTTP method used for the webhook's requests. To subscribe the webhook to Zendesk events, this must be "POST"
+ * @property {string} id - An auto-generated webhook id (read-only)
+ * @property {string} name - Webhook name
+ * @property {'json' | 'xml' | 'form_encoded'} request_format - The format of the data that the webhook will send. To subscribe the webhook to Zendesk events, this must be "json"
+ * @property {WebhookSigningSecret} [signing_secret] - Signing secret used to verify webhook requests
+ * @property {'active' | 'inactive'} status - Current status of the webhook
+ * @property {Array} [subscriptions] - Event subscriptions for the webhook. To subscribe the webhook to Zendesk events, specify one or more event types
+ * @property {string} [updated_at] - When the webhook was last updated (read-only)
+ * @property {string} [updated_by] - id of the user who last updated the webhook (read-only)
+ */
+
+/**
+ * @typedef {object} CreateOrUpdateWebhook
+ * @property {Partial<Webhook>} webhook - The webhook object to create or update.
+ */
+
+/**
+ * @typedef {object} WebhookSigningSecret
+ * @property {string} algorithm - The algorithm used to generate the signing secret like "sha256"
+ * @property {string} secret - The signing secret used to verify webhook requests
+ */
+
 /**
  * Webhooks client for interacting with the Zendesk Webhooks API.
  * @see {@link https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/}
@@ -14,7 +46,7 @@ class Webhooks extends Client {
 
   /**
    * List all webhooks.
-   * @returns {Promise<object>} A promise that resolves to the list of webhooks.
+   * @returns {Promise<Webhook>} A promise that resolves to the list of webhooks.
    * @see {@link https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/#list-webhooks}
    * @example const webhooks = await client.webhooks.list();
    */
@@ -25,7 +57,7 @@ class Webhooks extends Client {
   /**
    * Retrieve a specific webhook by ID.
    * @param {string} webhookID - The ID of the webhook to retrieve.
-   * @returns {Promise<{response: object, result: object}>} A promise that resolves to the specified webhook.
+   * @returns {Promise<{response: object, result: Webhook}>} A promise that resolves to the specified webhook.
    * @see {@link https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/#show-webhook}
    * @example const webhook = await client.webhooks.show('webhookID123');
    */
@@ -35,8 +67,8 @@ class Webhooks extends Client {
 
   /**
    * Create a new webhook.
-   * @param {object} webhook - The webhook data to create.
-   * @returns {Promise<{response: object, result: object}>} A promise that resolves to the created webhook.
+   * @param {CreateOrUpdateWebhook} webhook - The webhook data to create.
+   * @returns {Promise<{response: object, result: Webhook}>} A promise that resolves to the created webhook.
    * @see {@link https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/#create-or-clone-webhook}
    * @example
    * const newWebhook = {
@@ -51,7 +83,7 @@ class Webhooks extends Client {
   /**
    * Update a specific webhook by ID.
    * @param {string} webhookID - The ID of the webhook to update.
-   * @param {object} webhook - The updated webhook data.
+   * @param {CreateOrUpdateWebhook} webhook - The updated webhook data.
    * @returns {Promise<{response: object, result: object}>} A promise that resolves to the updated webhook.
    * @see {@link https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/#update-webhook}
    * @example
@@ -128,7 +160,7 @@ class Webhooks extends Client {
   /**
    * Retrieve the signing secret of a specific webhook.
    * @param {string} webhookID - The ID of the webhook.
-   * @returns {Promise<{response: object, result: object}>} A promise that resolves to the signing secret.
+   * @returns {Promise<{response: object, result: {signing_secret: WebhookSigningSecret}}>} A promise that resolves to the signing secret.
    * @see {@link https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/#show-webhook-signing-secret}
    * @example const secret = await client.webhooks.getSigningSecret('webhookID123');
    */
@@ -139,7 +171,7 @@ class Webhooks extends Client {
   /**
    * Reset the signing secret for a specific webhook.
    * @param {string} webhookID - The ID of the webhook.
-   * @returns {Promise<{response: object, result: object}>} A promise that resolves to the new signing secret.
+   * @returns {Promise<{response: object, result: {signing_secret: WebhookSigningSecret}}>} A promise that resolves to the new signing secret.
    * @see {@link https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/#reset-webhook-signing-secret}
    * @example const newSecret = await client.webhooks.resetSigningSecret('webhookID123');
    */