From 4185e24a0657fd8fe877b4f170ff7da9d3afd4ac Mon Sep 17 00:00:00 2001
From: SoSweetHam <sosweetham@gmail.com>
Date: Wed, 22 May 2024 20:34:24 +0530
Subject: [PATCH] feat: added docstrings

---
 README.md    | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/index.ts | 63 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 135 insertions(+)

diff --git a/README.md b/README.md
index c99d975..fa43230 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,74 @@
 # cardboard.js
 JS/TS Wrapper for the CardBoard API
+
+# Examples
+## Initial Setup
+```typescript
+import {config} from "dotenv"
+
+import { Cardboard } from "cardboard.js"
+
+config()
+
+const clientSecret = process.env.CLIENT_SECRET
+const clientId = process.env.CLIENT_ID
+
+if (!clientSecret) {
+    throw new Error("Missing client secret")
+}
+
+if (!clientId) {
+    throw new Error("Missing client id")
+}
+
+const cb = new Cardboard(clientId, clientSecret)
+```
+## Usage
+```typescript
+import express from "express"
+
+const app = express()
+
+app.use(express.json())
+
+// single user mock db, you would have something way more complicated here for multiple users and your app's own data
+let at=""
+
+// route setup in redirect uri on cardboard.ink
+app.get("/login", async (req, res) => {
+    const code = req.query.code as string
+
+    // initializes long term session on cardboard's end (30 days)
+    const loginData = await cb.exchangeInitialToken(code)
+
+    // your logic to set session in your app
+    at = loginData.access_token
+    res.send(loginData)
+    return
+})
+
+app.get("/logout", async (req, res) => {
+
+  // remove session on cardboard's end 
+  const logout = await cb.revokeToken(at)
+
+  // your logic to remove session in your app 
+  at = ""
+  res.send(logout)
+  return
+})
+
+app.get("/user", async (req, res) => {
+    if (at === "") {
+        res.send(`<h1>Not logged in</h1> <a href='https://cardboard.ink/auth?client_id=${clientId}'>Login</a>`)
+        return
+    }
+    const user = await cb.getUserInfo(at)
+    res.json(user)
+    return
+})
+
+app.listen(3000, () => {
+    console.log("Listening on port 3000")
+})
+```
\ No newline at end of file
diff --git a/src/index.ts b/src/index.ts
index 22c4919..6f5f723 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,10 +3,19 @@ import { URLSearchParams } from "url";
 import { GuildedUser, IGetToken, Alias, UserStatus, Content, Document, CustomReaction, AboutInfo } from "./types";
 
 export { GuildedUser, IGetToken, Alias, UserStatus, Content, Document, CustomReaction, AboutInfo };
+/**
+ * The main class for the cardboard api
+ */
 export class Cardboard {
   private _baseurl: string;
   private _axios: AxiosInstance;
+  /**
+   * The client id of the application
+   */
   protected client_id: string;
+  /**
+   * The client secret of the application
+   */
   protected client_secret: string;
 
   constructor(client_id: string, client_secret: string, local = false) {
@@ -20,6 +29,22 @@ export class Cardboard {
     this.client_secret = client_secret;
   }
 
+  /**
+   * @param code The code recieved from cardboard redirect according to the oauth2 flow
+   * @returns The token object 
+   * 
+   * ```ts
+   * app.get("/login", async (req, res) => {
+   *  const code = req.query.code as string
+   *  // initializes long term session on cardboard's end (30 days)
+   *  const loginData = await cb.exchangeInitialToken(code)
+   *  // your logic to set session in your app
+   *  at = loginData.access_token
+   *  res.send(loginData)
+   *  return
+   * })
+   * ```
+   */
   public async exchangeInitialToken(code: string): Promise<IGetToken> {
     const grant_type = "authorization_code";
     const response = await this._axios.post(
@@ -34,6 +59,10 @@ export class Cardboard {
     return response.data;
   }
 
+  /**
+   * @param refresh_token The refresh token recieved from the initial token exchange
+   * @returns The token object
+   */
   public async refreshToken(refresh_token: string): Promise<IGetToken> {
     const grant_type = "refresh_token";
     const response = await this._axios.post(
@@ -47,6 +76,21 @@ export class Cardboard {
     );
     return response.data;
   }
+
+  /**
+   * @param access_token The access token recieved from the initial token exchange
+   * @returns The token object
+   * ```ts
+   * app.get("/logout", async (req, res) => {
+   *  // remove session on cardboard's end 
+   *  const logout = await cb.revokeToken(at)
+   *  // your logic to remove session in your app 
+   *  at = ""
+   *  res.send(logout)
+   *  return
+   * })
+   * ```
+   */
   public async revokeToken(token: string): Promise<void> {
     await this._axios
       .post(
@@ -63,6 +107,10 @@ export class Cardboard {
     return;
   }
 
+  /**
+   * @param access_token The access token recieved from the initial token exchange
+   * @returns The validity of the token
+   */
   public async checkToken(access_token: string): Promise<any> {
     const token = access_token;
     const response = await this._axios.post(
@@ -72,6 +120,21 @@ export class Cardboard {
     return response.data;
   }
 
+  /**
+   * @param access_token The access token recieved from the initial token exchange
+   * @returns The user info
+   * ```ts
+   * app.get("/user", async (req, res) => {
+   *  if (at === "") {
+   *      res.send(`<h1>Not logged in</h1> <a href='https://cardboard.ink/auth?client_id=${clientId}'>Login</a>`)
+   *      return
+   *  }
+   *  const user = await cb.getUserInfo(at)
+   *  res.json(user)
+   *  return
+   * })
+   * ```
+   */
   public async getUserInfo(access_token: string): Promise<GuildedUser> {
     const response = await this._axios.get("users/@me", {
       headers: { authorization: `Bearer ${access_token}` },