Merge branch 'main' of github.com:atlassian/atlassian-connect-sample-app-node

Author: krazziekay

postinstall.ts

@@ -6,7 +6,9 @@ const envExampleFileName = `${envFileName}.example`;
 const envFilePath = path.resolve(__dirname, envFileName);
 const envExampleFilePath = path.resolve(__dirname, envExampleFileName);
 
-// Creates the .env file
+/**
+ * Creates the env file
+ */
 const createEnvFile = async () => {
     if (!fs.existsSync(envFilePath)) {
         await fs.copyFile(envExampleFilePath, envFilePath, (err) => {
@@ -19,6 +21,10 @@ const createEnvFile = async () => {
     }
 };
 
+/**
+ * This script creates an env file if there isn't one,
+ * The env file is based off from .env.example
+ */
 (async function main() {
     try {
         await createEnvFile();

prestart.ts

@@ -4,6 +4,11 @@ import * as path from 'path';
 const envFileName = '.env';
 const envFilePath = path.resolve(__dirname, envFileName);
 
+/**
+ * Fetching the list of running tunnels
+ *
+ * https://ngrok.com/docs/ngrok-agent/api/#request
+ */
 const callTunnel = async () => {
     const results = await Promise.all([
         fetch('http://tunnel:4040/api/tunnels').catch(() => undefined),
@@ -38,6 +43,10 @@ const waitForTunnel = async () => {
     }
 };
 
+
+/**
+ * This method update the APP_URL in the env file with the ngrok tunneled URL
+ */
 (async function main() {
     try {
         await waitForTunnel();

src/db.ts

@@ -2,6 +2,9 @@ import path from "path";
 import { chain, ExpChain, remove } from "lodash";
 import { JSONFile, Low } from "@commonify/lowdb";
 
+/**
+ * Type Definitions for the database
+ */
 export interface JiraTenant {
 	id: string;
 	url: string;
@@ -21,15 +24,22 @@ interface ConnectAppData {
 	logs: Log[];
 }
 
+// Configure lowdb to write to JSONFile
+const dbFile = path.join(process.cwd(), "db.json");
+const adapter = new JSONFile<ConnectAppData>(dbFile);
+
+// Default data to be added to JSON db
+const defaults = {
+	jiraTenants: [],
+	logs: []
+};
+
 // Extend Low class with a new `chain` field
 class LowWithLodash<T> extends Low<T> {
 	chain: ExpChain<this["data"]> = chain(this).get("data");
 }
 
-// Configure lowdb to write to JSONFile
-const dbFile = path.join(process.cwd(), "db.json");
-const adapter = new JSONFile<ConnectAppData>(dbFile);
-
+// Initializes the db
 const initialized = () => {
 	return (_target: unknown, _propertyKey: string, descriptor: TypedPropertyDescriptor<(...params: any[]) => Promise<any>>) => {
 		const fn = descriptor.value;
@@ -41,13 +51,9 @@ const initialized = () => {
 	};
 };
 
-// Default data to be added to JSON db
-const defaults = {
-	jiraTenants: [],
-	logs: []
-};
-
-// This is a stand in for any kind of DB/ORM library you'd like to use to store data
+/**
+ * This is a stand-in for any kind of DB/ORM library you'd like to use to store data0
+ */
 class ConnectAppDatabase extends LowWithLodash<ConnectAppData> {
 	constructor() {
 		super(adapter);

src/middlewares/connect-iframe-jwt-middleware.ts

@@ -7,14 +7,11 @@ import { fromExpressRequest } from "atlassian-jwt/dist/lib/jwt";
  * This middleware decodes the JWT token from Jira, verifies it
  * And sets the `clientKey` in `res.locals`
  * The tenant for each instance of the app is recognized based on this `clientKey`
- *
- * source: https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#decoding-and-verifying-a-jwt-token
- *
+ * https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#decoding-and-verifying-a-jwt-token
  */
 export const connectIframeJWTMiddleware = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
 
-	// const request = fromExpressRequest(req);
-	// This is the Jira instance url injected into the iframe url
+	// This query parameter is injected into the iframe url
 	const jwt = req.query.jwt as string;
 
 	// if JWT is missing, return a 401

src/routes/router.ts

@@ -9,23 +9,39 @@ import getMarkdownAndConvertToHtml from "../utils/markup";
 
 export const RootRouter = Router();
 
-// Healthcheck route to make sure the server works
-RootRouter.get("/healthcheck", (_req, res) => res.status(200).send("Works!"));
-
-// This is the Connect JSON app descriptor
+/************************************************************************************************************************
+ * Healthcheck
+	************************************************************************************************************************/
+RootRouter.get("/healthcheck", (_req, res) => res.status(200).send("Healthy!"));
+
+/************************************************************************************************************************
+ * Connect app descriptor
+ ************************************************************************************************************************/
 RootRouter.get("/atlassian-connect.json", connectDescriptorGet);
 
-// Public files like images and stylesheets
+/************************************************************************************************************************
+ * Public files(images, stylesheets)
+ ************************************************************************************************************************/
 RootRouter.use("/public", Static(path.join(process.cwd(), "static")));
 
-// The Connect lifecycle events as specified in the Connect JSON above
+/************************************************************************************************************************
+ * Connect lifecycle Events
+ ************************************************************************************************************************/
 RootRouter.use("/events", eventsRouter);
 
-// Jira webhooks we listen to as specified in the Connect JSON above
+/************************************************************************************************************************
+ * Webhooks
+ ************************************************************************************************************************/
 RootRouter.use("/webhooks", webhooksRouter);
 
+/************************************************************************************************************************
+ * Middlewares
+ ************************************************************************************************************************/
 RootRouter.use(connectIframeJWTMiddleware);
 
+/************************************************************************************************************************
+ * Views
+ ************************************************************************************************************************/
 RootRouter.get("/", (_req: Request, res: Response): void => {
 	res.render("introduction", {
 		pageContent: getMarkdownAndConvertToHtml("introduction.md")

src/routes/webhooks.ts

@@ -19,7 +19,6 @@ webhooksRouter.post("/jira/issue-created", async (req, res) => {
 });
 
 webhooksRouter.post("/jira/issue-updated", async (req, res) => {
-	// Mapping the host set during the installation with the url coming in from the webhooks
 	const host = new URL(req.body.user.self).origin;
 	const tenant = await database.findJiraTenant({ url: host });
 	await database.addLogs({
@@ -33,7 +32,6 @@ webhooksRouter.post("/jira/issue-updated", async (req, res) => {
 });
 
 webhooksRouter.post("/jira/issue-deleted", async (req, res) => {
-	// Mapping the host set during the installation with the url coming in from the webhooks
 	const host = new URL(req.body.user.self).origin;
 	const tenant = await database.findJiraTenant({ url: host });
 	await database.addLogs({

src/utils/markup.ts

@@ -5,6 +5,12 @@ import { marked } from "marked";
 
 const renderer = new marked.Renderer();
 
+/**
+ * Converting the two types of links in the markdown files
+ * 1. External URLs containing `http` or `https`
+ * 2. Internal URLs containing the Connect module keys
+ *    (Connect page navigation is handled in `static/js/index.js`)
+ */
 renderer.link = (href: string, _, text: string): string => {
 	if (href?.includes("https" || href?.includes("http"))) {
 		return `<a target="_blank" href="${href}">${text}</a>`;
@@ -13,11 +19,15 @@ renderer.link = (href: string, _, text: string): string => {
 		return `<span class="link-span" id="${page}" data-connect-module-key="${page}">${text}</span>`;
 	}
 };
+
+/**
+ * Converts the content of the markdown files to corresponding HTML
+ */
 const getMarkdownAndConvertToHtml = (fileName: string): string => {
 	const filePath = path.join(__dirname, "..", "content", fileName);
 	const contents = fs.readFileSync(filePath);
 	// TODO - see if there's a way to modify the way we are using marked.js so we can pass data directly to HTML elements
-	const markdownToHtml = marked.parse(contents.toString(), { renderer: renderer });
+	const markdownToHtml = marked.parse(contents.toString(), { renderer });
 
 	return sanitizeHtml(markdownToHtml, {
 		allowedAttributes: {
@@ -27,5 +37,4 @@ const getMarkdownAndConvertToHtml = (fileName: string): string => {
 	});
 };
 
-
 export default getMarkdownAndConvertToHtml;