Skip to content

Commit

Permalink
feat: added docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
sosweetham committed May 22, 2024
1 parent f630bf8 commit 4185e24
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 0 deletions.
72 changes: 72 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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")
})
```
63 changes: 63 additions & 0 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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}` },
Expand Down

0 comments on commit 4185e24

Please sign in to comment.