From 8bdaa99535efcd7ac51518fb21c1e478c27acfa4 Mon Sep 17 00:00:00 2001
From: dirkluijk <mail@dirkluijk.nl>
Date: Fri, 3 Jan 2025 15:26:10 +0100
Subject: [PATCH] docs: add JSDocs

---
 README.md                          |  6 ++++--
 main.ts                            |  6 +++---
 src/utils/spotify-authorization.ts |  8 ++++++--
 src/utils/spotify.ts               | 30 ++++++++++++++++++++++++++++++
 4 files changed, 43 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 4c28e0a..788fecc 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,13 @@ Simple CLI script to sync Spotify tracks from a raw text to a playlist.
 ## Usage
 
 Install Deno, and run:
+
 ```bash
 deno run --allow-net jsr:@dirkluijk/text-to-playlist <inputFileOrText> --playlist <playlistUrl>
 ```
 
 ## Options
+
 ```
 -h, --help                            - Show this help.                                                                  
 -V, --version                         - Show the version number for this program.                                        
@@ -21,5 +23,5 @@ deno run --allow-net jsr:@dirkluijk/text-to-playlist <inputFileOrText> --playlis
 
 ## Contributors
 
-* [@dirkluijk](https://github.com/dirkluijk) - Deno fork
-* [@janluijk](https://github.com/janluijk) - original Python implementation
+- [@dirkluijk](https://github.com/dirkluijk) - Deno fork
+- [@janluijk](https://github.com/janluijk) - original Python implementation
diff --git a/main.ts b/main.ts
index 7d19cd5..b95e795 100644
--- a/main.ts
+++ b/main.ts
@@ -19,7 +19,7 @@ const { args, options } = await new Command()
     "The Spotify Playlist URL to add to tracks to",
     { required: true },
   )
-  .option('-D, --debug', 'Outputs debugging logs')
+  .option("-D, --debug", "Outputs debugging logs")
   .option(
     "--remove-duplicates [flag:boolean]",
     "Whether to filter out duplicates from input",
@@ -50,8 +50,8 @@ const trackUrls = removeDuplicates
 const tracks = trackUrls.map(Track.fromUrl);
 
 if (options.debug) {
-  console.debug('Found tracks:');
-  console.table(tracks.map((it) => it.toUrl()))
+  console.debug("Found tracks:");
+  console.table(tracks.map((it) => it.toUrl()));
 }
 
 const currentTracks = await new PageIterator(
diff --git a/src/utils/spotify-authorization.ts b/src/utils/spotify-authorization.ts
index a50e123..70ecfdd 100644
--- a/src/utils/spotify-authorization.ts
+++ b/src/utils/spotify-authorization.ts
@@ -8,9 +8,10 @@ const REDIRECT_URI = "http://localhost:8888/callback";
 
 const [codeVerifier, codeChallenge] = await createPkceChallenge();
 
+/**
+ * Starts a local web server to accept the callback from the Spotify Authorization flow.
+ */
 function waitForAuthorization(options: { port: number }): Promise<string> {
-  // wait for user to have accepted
-  // opens web server to accept the callback
   return new Promise<string>((resolve, reject) => {
     const abortController = new AbortController();
     const server = Deno.serve({
@@ -52,8 +53,11 @@ export async function retrieveAccessToken(): Promise<string> {
       }).toString(),
   );
 
+  // wait for user to have accepted
+  // opens web server to accept the callback
   const code = await waitForAuthorization({ port: 8888 });
 
+  // now request the access token based on the authorization code
   const { access_token } = await wretch("https://accounts.spotify.com/api/token")
     .addon(FormUrlAddon)
     .formUrl({
diff --git a/src/utils/spotify.ts b/src/utils/spotify.ts
index 417ae4c..af7bb05 100644
--- a/src/utils/spotify.ts
+++ b/src/utils/spotify.ts
@@ -1,6 +1,13 @@
+/**
+ * Represents a Spotify track.
+ */
 export class Track {
   constructor(public id: string) {}
 
+  /**
+   * Parses a track from its Spotify URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   static fromUrl(trackUrl: string) {
     const pattern = new URLPattern("https://open.spotify.com/track/:id");
     const result = pattern.exec(trackUrl);
@@ -12,18 +19,33 @@ export class Track {
     return new Track(result.pathname.groups.id);
   }
 
+  /**
+   * Returns the Spotify track URI.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUri(): string {
     return `spotify:track:${this.id}`;
   }
 
+  /**
+   * Returns the Spotify track URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUrl(): string {
     return `https://open.spotify.com/track/${this.id}`;
   }
 }
 
+/**
+ * Represents a Spotify playlist.
+ */
 export class Playlist {
   constructor(public id: string) {}
 
+  /**
+   * Parses a playlist from its Spotify URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   static fromUrl(playlistUrl: string) {
     const pattern = new URLPattern("https://open.spotify.com/playlist/:id");
     const result = pattern.exec(playlistUrl);
@@ -35,10 +57,18 @@ export class Playlist {
     return new Playlist(result.pathname.groups.id);
   }
 
+  /**
+   * Returns the Spotify playlist URI.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUri(): string {
     return `spotify:playlist:${this.id}`;
   }
 
+  /**
+   * Returns the Spotify playlist URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUrl(): string {
     return `https://open.spotify.com/playlist/${this.id}`;
   }