From 71da57773e5ec5db4de6c6febf2c279896df42d4 Mon Sep 17 00:00:00 2001
From: Tom Moor <tom.moor@gmail.com>
Date: Sun, 24 Jul 2022 14:09:43 +0100
Subject: [PATCH] docs

---
 server/commands/accountProvisioner.ts | 24 ++++++++++++++++++++++++
 server/commands/teamProvisioner.ts    | 12 ++++++++++++
 server/commands/userProvisioner.ts    | 16 ++++++++++++++++
 3 files changed, 52 insertions(+)

diff --git a/server/commands/accountProvisioner.ts b/server/commands/accountProvisioner.ts
index f576f8393..ff4d0d017 100644
--- a/server/commands/accountProvisioner.ts
+++ b/server/commands/accountProvisioner.ts
@@ -13,29 +13,53 @@ import teamProvisioner from "./teamProvisioner";
 import userProvisioner from "./userProvisioner";
 
 type Props = {
+  /** The IP address of the incoming request */
   ip: string;
+  /** Details of the user logging in from SSO provider */
   user: {
+    /** The displayed name of the user */
     name: string;
+    /** The email address of the user */
     email: string;
+    /** The public url of an image representing the user */
     avatarUrl?: string | null;
+    /** The username of the user */
     username?: string;
   };
+  /** Details of the team the user is logging into */
   team: {
+    /**
+     * The internal ID of the team that is being logged into based on the
+     * subdomain that the request came from, if any.
+     */
     teamId?: string;
+    /** The displayed name of the team */
     name: string;
+    /** The domain name from the email of the user logging in */
     domain?: string;
+    /** The preferred subdomain to provision for the team if not yet created */
     subdomain: string;
+    /** The public url of an image representing the team */
     avatarUrl?: string | null;
   };
+  /** Details of the authentication provider being used */
   authenticationProvider: {
+    /** The name of the authentication provider, eg "google" */
     name: string;
+    /** External identifier of the authentication provider */
     providerId: string;
   };
+  /** Details of the authentication from SSO provider */
   authentication: {
+    /** External identifier of the user in the authentication provider  */
     providerId: string;
+    /** The scopes granted by the access token */
     scopes: string[];
+    /** The token provided by the authentication provider */
     accessToken?: string;
+    /** The refresh token provided by the authentication provider */
     refreshToken?: string;
+    /** A number of seconds that the given access token expires in */
     expiresIn?: number;
   };
 };
diff --git a/server/commands/teamProvisioner.ts b/server/commands/teamProvisioner.ts
index 621b46c31..8c93cc49f 100644
--- a/server/commands/teamProvisioner.ts
+++ b/server/commands/teamProvisioner.ts
@@ -17,15 +17,27 @@ type TeamProvisionerResult = {
 };
 
 type Props = {
+  /**
+   * The internal ID of the team that is being logged into based on the
+   * subdomain that the request came from, if any.
+   */
   teamId?: string;
+  /** The displayed name of the team */
   name: string;
+  /** The domain name from the email of the user logging in */
   domain?: string;
+  /** The preferred subdomain to provision for the team if not yet created */
   subdomain: string;
+  /** The public url of an image representing the team */
   avatarUrl?: string | null;
+  /** Details of the authentication provider being used */
   authenticationProvider: {
+    /** The name of the authentication provider, eg "google" */
     name: string;
+    /** External identifier of the authentication provider */
     providerId: string;
   };
+  /** The IP address of the incoming request */
   ip: string;
 };
 
diff --git a/server/commands/userProvisioner.ts b/server/commands/userProvisioner.ts
index 9e51ddb05..280a8a4af 100644
--- a/server/commands/userProvisioner.ts
+++ b/server/commands/userProvisioner.ts
@@ -14,20 +14,36 @@ type UserProvisionerResult = {
 };
 
 type Props = {
+  /** The displayed name of the user */
   name: string;
+  /** The email address of the user */
   email: string;
+  /** The username of the user */
   username?: string;
+  /** Provision the new user as an administrator */
   isAdmin?: boolean;
+  /** The public url of an image representing the user */
   avatarUrl?: string | null;
+  /**
+   * The internal ID of the team that is being logged into based on the
+   * subdomain that the request came from, if any.
+   */
   teamId: string;
+  /** Only match against existing user accounts using email, do not create a new account */
   emailMatchOnly?: boolean;
+  /** The IP address of the incoming request */
   ip: string;
   authentication: {
     authenticationProviderId: string;
+    /** External identifier of the user in the authentication provider  */
     providerId: string;
+    /** The scopes granted by the access token */
     scopes: string[];
+    /** The token provided by the authentication provider */
     accessToken?: string;
+    /** The refresh token provided by the authentication provider */
     refreshToken?: string;
+    /** The timestamp when the access token expires */
     expiresAt?: Date;
   };
 };