doc: add docs to readme

.github/workflows/doc-gen.yml

@@ -0,0 +1,22 @@
+name: Deploy docs
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Install dependencies
+        run: npm i
+      - name: Build docs
+        run: npm run docs
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: docs

.gitignore

@@ -125,3 +125,5 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+docs

.npmignore

@@ -126,3 +126,4 @@ out
 .pnp.*
 
 src
+docs

README.md

@@ -2,6 +2,8 @@
 
 This is the API wrapper for [Piped](https://github.com/TeamPiped/Piped) in Node.js (Typescript).
 
+[Docs](https://artegoser.github.io/piped-api/)
+
 ## Installation
 
 ```bash

package-lock.json

@@ -18,6 +18,7 @@
         "@typescript-eslint/parser": "^6.2.1",
         "eslint": "^8.46.0",
         "ts-node": "^10.9.1",
+        "typedoc": "^0.24.8",
         "typescript": "^5.1.6"
       }
     },
@@ -495,6 +496,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/ansi-sequence-parser": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz",
+      "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==",
+      "dev": true
+    },
     "node_modules/ansi-styles": {
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
@@ -1238,6 +1245,12 @@
       "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==",
       "dev": true
     },
+    "node_modules/jsonc-parser": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz",
+      "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==",
+      "dev": true
+    },
     "node_modules/levn": {
       "version": "0.4.1",
       "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz",
@@ -1284,12 +1297,30 @@
         "node": ">=10"
       }
     },
+    "node_modules/lunr": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
+      "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==",
+      "dev": true
+    },
     "node_modules/make-error": {
       "version": "1.3.6",
       "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
       "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
       "dev": true
     },
+    "node_modules/marked": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz",
+      "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==",
+      "dev": true,
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/merge2": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
@@ -1613,6 +1644,18 @@
         "node": ">=8"
       }
     },
+    "node_modules/shiki": {
+      "version": "0.14.3",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.3.tgz",
+      "integrity": "sha512-U3S/a+b0KS+UkTyMjoNojvTgrBHjgp7L6ovhFVZsXmBGnVdQ4K4U9oK0z63w538S91ATngv1vXigHCSWOwnr+g==",
+      "dev": true,
+      "dependencies": {
+        "ansi-sequence-parser": "^1.1.0",
+        "jsonc-parser": "^3.2.0",
+        "vscode-oniguruma": "^1.7.0",
+        "vscode-textmate": "^8.0.0"
+      }
+    },
     "node_modules/slash": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
@@ -1755,6 +1798,51 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/typedoc": {
+      "version": "0.24.8",
+      "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.24.8.tgz",
+      "integrity": "sha512-ahJ6Cpcvxwaxfu4KtjA8qZNqS43wYt6JL27wYiIgl1vd38WW/KWX11YuAeZhuz9v+ttrutSsgK+XO1CjL1kA3w==",
+      "dev": true,
+      "dependencies": {
+        "lunr": "^2.3.9",
+        "marked": "^4.3.0",
+        "minimatch": "^9.0.0",
+        "shiki": "^0.14.1"
+      },
+      "bin": {
+        "typedoc": "bin/typedoc"
+      },
+      "engines": {
+        "node": ">= 14.14"
+      },
+      "peerDependencies": {
+        "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x"
+      }
+    },
+    "node_modules/typedoc/node_modules/brace-expansion": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
+      "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+      "dev": true,
+      "dependencies": {
+        "balanced-match": "^1.0.0"
+      }
+    },
+    "node_modules/typedoc/node_modules/minimatch": {
+      "version": "9.0.3",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz",
+      "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==",
+      "dev": true,
+      "dependencies": {
+        "brace-expansion": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/typescript": {
       "version": "5.1.6",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.1.6.tgz",
@@ -1783,6 +1871,18 @@
       "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==",
       "dev": true
     },
+    "node_modules/vscode-oniguruma": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz",
+      "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==",
+      "dev": true
+    },
+    "node_modules/vscode-textmate": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz",
+      "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==",
+      "dev": true
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",

package.json

@@ -13,7 +13,8 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "docs": "typedoc src/index.ts",
+    "prepublishOnly": "npm run build && npm run docs"
   },
   "keywords": [
     "api",
@@ -35,6 +36,7 @@
     "@typescript-eslint/parser": "^6.2.1",
     "eslint": "^8.46.0",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.24.8",
     "typescript": "^5.1.6"
   },
   "dependencies": {

src/index.ts

@@ -1,152 +1,2 @@
-import axios from "axios";
+export { PipedAPI } from "./piped-api";
-import {
+export * as Types from "./responses.interface";
-  Channel,
-  Comments,
-  NextPageChannel,
-  NextPagePlaylist,
-  Playlist,
-  Search,
-  Sponsors,
-  Streams,
-  Video,
-} from "./responses.interface";
-
-export class PipedAPI {
-  host: string;
-  constructor(host: string = "https://pipedapi.kavin.rocks") {
-    this.host = host;
-  }
-
-  /**
-   * Retrieves data from the specified URL.
-   *
-   * @param {string} url - The URL from which to retrieve data.
-   * @return {Promise<any>} - A Promise that resolves to the parsed JSON data.
-   */
-  private async _get(url: string) {
-    const data = await axios.get(`${this.host}${url}`);
-    return data.data;
-  }
-
-  /**
-   * Retrieves the trending videos for a specific region.
-   *
-   * @param {string} region - The region for which to retrieve trending videos.
-   * @return {Promise<Video[]>} - A promise that resolves to an array of Video objects representing the trending videos.
-   */
-  async trending(region: string): Promise<Video[]> {
-    return await this._get(`/trending?region=${region}`);
-  }
-
-  /**
-   * Retrieves the streams for a given video ID.
-   *
-   * @param {string} videoId - The ID of the video.
-   * @return {Promise<Streams>} A promise that resolves to the streams for the given video ID.
-   */
-  async streams(videoId: string): Promise<Streams> {
-    return await this._get(`/streams/${videoId}`);
-  }
-
-  /**
-   * Retrieves comments for a specific video.
-   *
-   * @param {string} videoId - The ID of the video for which to retrieve comments.
-   * @param {string} nextpage - The JSON encoded nextpage variable, to be sent as a query string (optional).
-   * @returns {Promise<Comments>} A Promise that resolves to the comments for the video.
-   */
-  async comments(videoId: string, nextpage?: string): Promise<Comments> {
-    return nextpage
-      ? await this._get(`/nextpage/comments/${videoId}?nextpage=${nextpage}`)
-      : await this._get(`/comments/${videoId}`);
-  }
-
-  /**
-   * Retrieves a channel by its ID.
-   *
-   * @param {string} id - The ID of the channel to retrieve.
-   * @param {string} nextpage - The JSON encoded nextpage variable, to be sent as a query string (optional).
-   * @return {Promise<Channel | NextPageChannel>} A Promise that resolves to the retrieved Channel object.
-   */
-  async channel(
-    id: string,
-    nextpage?: string
-  ): Promise<Channel | NextPageChannel> {
-    return nextpage
-      ? await this._get(`/nextpage/channel/${id}?nextpage=${nextpage}`)
-      : await this._get(`/channel/${id}`);
-  }
-
-  /**
-   * Retrieves a channel by its name.
-   *
-   * @param {string} name - The name of the channel.
-   * @return {Promise<Channel>} A promise that resolves to the channel object.
-   */
-  async channelByName(name: string): Promise<Channel> {
-    return await this._get(`/c/${name}`);
-  }
-
-  /**
-   * Retrieves a user by their name.
-   *
-   * @param {string} name - The name of the user.
-   * @return {Promise<Channel>} A Promise that resolves to the user's channel.
-   */
-  async user(name: string): Promise<Channel> {
-    return await this._get(`/user/${name}`);
-  }
-
-  /**
-   * Retrieves a playlist based on its ID.
-   *
-   * @param {string} id - The ID of the playlist to retrieve.
-   * @param {string} nextpage - The token for the next page of results (optional).
-   * @return {Promise<Playlist | NextPagePlaylist>} A Promise that resolves to a Playlist or NextPagePlaylist object.
-   */
-  async playlist(
-    id: string,
-    nextpage?: string
-  ): Promise<Playlist | NextPagePlaylist> {
-    return nextpage
-      ? await this._get(`/nextpage/playlists/${id}?nextpage=${nextpage}`)
-      : await this._get(`/playlists/${id}`);
-  }
-
-  /**
-   * Retrieves suggestions based on the given query.
-   *
-   * @param {string} query - The query string to search for suggestions.
-   * @return {Promise<string[]>} A promise that resolves to an array of string suggestions.
-   */
-  async suggestions(query: string): Promise<string[]> {
-    return await this._get(`/suggestions?query=${query}`);
-  }
-
-  /**
-   * Retrieves sponsors based on the provided ID and category.
-   *
-   * @param {string} id - The ID of the video.
-   * @param {string[]} category - The category of sponsors you would like to skip. Example: ["sponsor"].
-   * @return {Promise<Sponsors>} A promise that resolves to the sponsors.
-   */
-  async sponsors(
-    id: string,
-    category: string[] = ["sponsor"]
-  ): Promise<Sponsors> {
-    return await this._get(
-      `/sponsors/${id}?category=${JSON.stringify(category)}`
-    );
-  }
-
-  /**
-   * Searches videos for a given query with an optional filter.
-   *
-   * @param {string} query - The query to search for.
-   * @param {string} [filter="all"] - The optional filter to apply.
-   * @returns {Promise<Search>} - A Promise that resolves to the search results.
-   */
-  async search(query: string, filter: string = "all"): Promise<Search> {
-    return await this._get(`/search?q=${query}&filter=${filter}`);
-  }
-}

src/piped-api.ts

@@ -0,0 +1,152 @@
+import axios from "axios";
+import {
+  Channel,
+  Comments,
+  NextPageChannel,
+  NextPagePlaylist,
+  Playlist,
+  Search,
+  Sponsors,
+  Streams,
+  Video,
+} from "./responses.interface";
+
+export class PipedAPI {
+  host: string;
+  constructor(host: string = "https://pipedapi.kavin.rocks") {
+    this.host = host;
+  }
+
+  /**
+   * Retrieves data from the specified URL.
+   *
+   * @param {string} url - The URL from which to retrieve data.
+   * @return {Promise<any>} - A Promise that resolves to the parsed JSON data.
+   */
+  private async _get(url: string) {
+    const data = await axios.get(`${this.host}${url}`);
+    return data.data;
+  }
+
+  /**
+   * Retrieves the trending videos for a specific region.
+   *
+   * @param {string} region - The region for which to retrieve trending videos.
+   * @return {Promise<Video[]>} - A promise that resolves to an array of Video objects representing the trending videos.
+   */
+  async trending(region: string): Promise<Video[]> {
+    return await this._get(`/trending?region=${region}`);
+  }
+
+  /**
+   * Retrieves the streams for a given video ID.
+   *
+   * @param {string} videoId - The ID of the video.
+   * @return {Promise<Streams>} A promise that resolves to the streams for the given video ID.
+   */
+  async streams(videoId: string): Promise<Streams> {
+    return await this._get(`/streams/${videoId}`);
+  }
+
+  /**
+   * Retrieves comments for a specific video.
+   *
+   * @param {string} videoId - The ID of the video for which to retrieve comments.
+   * @param {string} nextpage - The JSON encoded nextpage variable, to be sent as a query string (optional).
+   * @returns {Promise<Comments>} A Promise that resolves to the comments for the video.
+   */
+  async comments(videoId: string, nextpage?: string): Promise<Comments> {
+    return nextpage
+      ? await this._get(`/nextpage/comments/${videoId}?nextpage=${nextpage}`)
+      : await this._get(`/comments/${videoId}`);
+  }
+
+  /**
+   * Retrieves a channel by its ID.
+   *
+   * @param {string} id - The ID of the channel to retrieve.
+   * @param {string} nextpage - The JSON encoded nextpage variable, to be sent as a query string (optional).
+   * @return {Promise<Channel | NextPageChannel>} A Promise that resolves to the retrieved Channel object.
+   */
+  async channel(
+    id: string,
+    nextpage?: string
+  ): Promise<Channel | NextPageChannel> {
+    return nextpage
+      ? await this._get(`/nextpage/channel/${id}?nextpage=${nextpage}`)
+      : await this._get(`/channel/${id}`);
+  }
+
+  /**
+   * Retrieves a channel by its name.
+   *
+   * @param {string} name - The name of the channel.
+   * @return {Promise<Channel>} A promise that resolves to the channel object.
+   */
+  async channelByName(name: string): Promise<Channel> {
+    return await this._get(`/c/${name}`);
+  }
+
+  /**
+   * Retrieves a user by their name.
+   *
+   * @param {string} name - The name of the user.
+   * @return {Promise<Channel>} A Promise that resolves to the user's channel.
+   */
+  async user(name: string): Promise<Channel> {
+    return await this._get(`/user/${name}`);
+  }
+
+  /**
+   * Retrieves a playlist based on its ID.
+   *
+   * @param {string} id - The ID of the playlist to retrieve.
+   * @param {string} nextpage - The token for the next page of results (optional).
+   * @return {Promise<Playlist | NextPagePlaylist>} A Promise that resolves to a Playlist or NextPagePlaylist object.
+   */
+  async playlist(
+    id: string,
+    nextpage?: string
+  ): Promise<Playlist | NextPagePlaylist> {
+    return nextpage
+      ? await this._get(`/nextpage/playlists/${id}?nextpage=${nextpage}`)
+      : await this._get(`/playlists/${id}`);
+  }
+
+  /**
+   * Retrieves suggestions based on the given query.
+   *
+   * @param {string} query - The query string to search for suggestions.
+   * @return {Promise<string[]>} A promise that resolves to an array of string suggestions.
+   */
+  async suggestions(query: string): Promise<string[]> {
+    return await this._get(`/suggestions?query=${query}`);
+  }
+
+  /**
+   * Retrieves sponsors based on the provided ID and category.
+   *
+   * @param {string} id - The ID of the video.
+   * @param {string[]} category - The category of sponsors you would like to skip. Example: ["sponsor"].
+   * @return {Promise<Sponsors>} A promise that resolves to the sponsors.
+   */
+  async sponsors(
+    id: string,
+    category: string[] = ["sponsor"]
+  ): Promise<Sponsors> {
+    return await this._get(
+      `/sponsors/${id}?category=${JSON.stringify(category)}`
+    );
+  }
+
+  /**
+   * Searches videos for a given query with an optional filter.
+   *
+   * @param {string} query - The query to search for.
+   * @param {string} [filter="all"] - The optional filter to apply.
+   * @returns {Promise<Search>} - A Promise that resolves to the search results.
+   */
+  async search(query: string, filter: string = "all"): Promise<Search> {
+    return await this._get(`/search?q=${query}&filter=${filter}`);
+  }
+}