docs: add TSDoc comments and resolve lint errors

.eslintrc

@@ -63,7 +63,7 @@
           "block",
           "block-like"
         ]
-      },
+      }
     ],
     "tsdoc/syntax": "warn"
   },

src/services/metaphor.ts

@@ -1,42 +1,122 @@
 import defaultKy from 'ky'
-import { z } from 'zod'
 
 export const METAPHOR_API_BASE_URL = 'https://api.metaphor.systems'
 
-// https://metaphorapi.readme.io/reference/search
-export const MetaphorSearchInputSchema = z.object({
-  query: z.string(),
-  numResults: z.number().optional(),
-  useQueryExpansion: z.boolean().optional(),
-  includeDomains: z.array(z.string()).optional(),
-  excludeDomains: z.array(z.string()).optional(),
-  startCrawlDate: z.string().optional(),
-  endCrawlDate: z.string().optional(),
-  startPublishedDate: z.string().optional(),
-  endPublishedDate: z.string().optional()
-})
+/**
+ * Metaphor search API input parameters.
+ *
+ * @see {@link https://metaphorapi.readme.io/reference/search}
+ */
+export type MetaphorSearchInput = {
+  /** A Metaphor-optimized query string. */
+  query: string
 
-export type MetaphorSearchInput = z.infer<typeof MetaphorSearchInputSchema>
+  /**
+   * Number of search results to return.
+   * Maximum is 500. Default is 100 if not specified.
+   */
+  numResults?: number
 
-export const MetaphorSearchOutputSchema = z.object({
-  results: z.array(
-    z.object({
-      author: z.string().nullable(),
-      publishedDate: z.string().nullable(),
-      title: z.string().nullable(),
-      score: z.number(),
-      url: z.string()
-    })
-  )
-})
+  /**
+   * Optional beta flag.
+   * If true, returns good results without Metaphor syntax.
+   * For example, Query "thought pieces about synthetic biology" should return good results, even though query is not Metaphor-optimized.
+   */
+  useQueryExpansion?: boolean
 
-export type MetaphorSearchOutput = z.infer<typeof MetaphorSearchOutputSchema>
+  /**
+   * List of domains to include in the search.
+   * If specified, results will only come from these domains.
+   * Only one of includeDomains and excludeDomains should be specified.
+   */
+  includeDomains?: string[]
+
+  /**
+   * List of domains to exclude in the search.
+   * If specified, results will exclude these domains.
+   * Only one of includeDomains and excludeDomains should be specified.
+   */
+  excludeDomains?: string[]
+
+  /**
+   * "Crawl date" refers to the date that Metaphor discovered a link, which is more granular and can be more useful than published date.
+   * If startCrawlDate is specified, results will only include links that were crawled after startCrawlDate.
+   * Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
+   */
+  startCrawlDate?: string
+
+  /**
+   * "Crawl date" refers to the date that Metaphor discovered a link, which is more granular and can be more useful than published date.
+   * If endCrawlDate is specified, results will only include links that were crawled before endCrawlDate.
+   * Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
+   */
+  endCrawlDate?: string
+
+  /**
+   * If specified, only links with a published date after startPublishedDate will be returned.
+   * Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
+   * Note that for some links, we have no published date, and these links will be excluded from the results if startPublishedDate is specified.
+   */
+  startPublishedDate?: string
+
+  /**
+   * If specified, only links with a published date before endPublishedDate will be returned.
+   * Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
+   * Note that for some links, we have no published date, and these links will be excluded from the results if endPublishedDate is specified.
+   */
+  endPublishedDate?: string
+}
+
+/**
+ * Result returned by the Metaphor Search API.
+ */
+export type MetaphorSearchOutput = {
+  results: {
+    /**
+     * The URL of the page.
+     */
+    url: string
+
+    /**
+     * The title of the page.
+     * This value can be null if the title is not available or cannot be determined.
+     */
+    title: string | null
+
+    /**
+     * The author of the content, if applicable.
+     * This value can be null if the author is not available or cannot be determined.
+     */
+    author: string | null
+
+    /**
+     * The estimated date the page was published, in YYYY-MM-DD format.
+     * This value can be null if the published date is not available or cannot be determined.
+     */
+    publishedDate: string | null
+
+    /**
+     * A number from 0 to 1 representing the similarity between the query and the result.
+     */
+    score: number
+  }[]
+}
 
 export class MetaphorClient {
-  api: typeof defaultKy
+  /**
+   * HTTP client for the Metaphor API.
+   */
+  readonly api: typeof defaultKy
 
-  apiKey: string
-  apiBaseUrl: string
+  /**
+   * Metaphor API key.
+   */
+  readonly apiKey: string
+
+  /**
+   * Metaphor API base URL.
+   */
+  readonly apiBaseUrl: string
 
   constructor({
     apiKey = process.env.METAPHOR_API_KEY,
@@ -59,6 +139,9 @@ export class MetaphorClient {
     })
   }
 
+  /**
+   * Returns a list of links relevant to your query.
+   */
   async search(params: MetaphorSearchInput) {
     return this.api
       .post('search', {

src/services/novu.ts

@@ -5,6 +5,9 @@ import defaultKy from 'ky'
  */
 export const NOVU_API_BASE_URL = 'https://api.novu.co/v1'
 
+/**
+ * Novu subscriber object.
+ */
 export type NovuSubscriber = {
   /**
    * Unique identifier for the subscriber. This can be any value that is meaningful to your application such as a user ID stored in your database or a unique email address.
@@ -34,6 +37,8 @@ export type NovuSubscriber = {
 
 /**
  * Response from the Novu API when triggering an event.
+ *
+ * @see {@link https://docs.novu.co/api/client-libraries#trigger-event}
  */
 export type NovuTriggerEventResponse = {
   /**
@@ -87,7 +92,7 @@ export type NovuTriggerOptions = {
  */
 export class NovuClient {
   /**
-   * Instance of ky for making requests to the Novu API.
+   * HTTP client for interacting with the Novu API.
    */
   api: typeof defaultKy
 

src/services/twilio-conversation.ts

@@ -427,6 +427,7 @@ export class TwilioConversationClient {
     const { conversations } = await this.findParticipantConversations(
       recipientPhoneNumber
     )
+
     for (const conversation of conversations) {
       await this.removeParticipant({
         conversationSid: conversation.conversation_sid,