chore: docs finalized for stp and others

api/src/controllers/auth.ts

@@ -19,7 +19,7 @@ export default class AuthController {
     delete AuthController.authCodes[userId][clientId]
 
   /**
-   * Accept a valid username/password, plus a CLIENT_ID, and return an AUTH_CODE
+   * @summary Accept a valid username/password, plus a CLIENT_ID, and return an AUTH_CODE
    *
    */
   @Example<AuthorizeResponse>({
@@ -33,7 +33,7 @@ export default class AuthController {
   }
 
   /**
-   * Accepts client/auth code and returns access/refresh tokens
+   * @summary Accepts client/auth code and returns access/refresh tokens
    *
    */
   @Example<TokenResponse>({
@@ -46,7 +46,7 @@ export default class AuthController {
   }
 
   /**
-   * Returns new access/refresh tokens
+   * @summary Returns new access/refresh tokens
    *
    */
   @Example<TokenResponse>({
@@ -62,7 +62,7 @@ export default class AuthController {
   }
 
   /**
-   * Logout terminate access/refresh tokens and returns nothing
+   * @summary Logout terminate access/refresh tokens and returns nothing
    *
    */
   @Security('bearerAuth')

api/src/controllers/client.ts

@@ -7,7 +7,7 @@ import Client, { ClientPayload } from '../model/Client'
 @Tags('Client')
 export default class ClientController {
   /**
-   * Create client with the following attributes: ClientId, ClientSecret. Admin only task.
+   * @summary Create client with the following attributes: ClientId, ClientSecret. Admin only task.
    *
    */
   @Example<ClientPayload>({

api/src/controllers/drive.ts

@@ -13,7 +13,7 @@ import {
 import { fileExists, readFile, createFile } from '@sasjs/utils'
 import { createFileTree, ExecutionController, getTreeExample } from '.'
 
-import { FileTree, isFileQuery, isFileTree, TreeNode } from '../types'
+import { FileTree, isFileTree, TreeNode } from '../types'
 import path from 'path'
 import { getTmpFilesFolderPath } from '../utils'
 
@@ -77,7 +77,7 @@ const execDeployErrorResponse: DeployResponse = {
 @Tags('Drive')
 export class DriveController {
   /**
-   * Creates/updates files within SASjs Drive using provided payload.
+   * @summary Creates/updates files within SASjs Drive using provided payload.
    *
    */
   @Example<DeployResponse>(successDeployResponse)
@@ -89,8 +89,9 @@ export class DriveController {
   }
 
   /**
-   * Get file from SASjs Drive
-   *
+   * @summary Get file from SASjs Drive
+   * @query filePath Location of SAS program
+   * @example filePath "/Public/somefolder/some.file"
    */
   @Example<GetFileResponse>({
     status: 'success',
@@ -106,7 +107,7 @@ export class DriveController {
   }
 
   /**
-   * Modify a file in SASjs Drive
+   * @summary Modify a file in SASjs Drive
    *
    */
   @Example<UpdateFileResponse>({
@@ -124,7 +125,7 @@ export class DriveController {
   }
 
   /**
-   * Fetch file tree within SASjs Drive.
+   * @summary Fetch file tree within SASjs Drive.
    *
    */
   @Get('/filetree')

api/src/controllers/group.ts

@@ -33,7 +33,7 @@ interface GroupDetailsResponse {
 @Tags('Group')
 export default class GroupController {
   /**
-   * Get list of all groups (groupName and groupDescription). All users can request this.
+   * @summary Get list of all groups (groupName and groupDescription). All users can request this.
    *
    */
   @Example<GroupResponse[]>([
@@ -49,7 +49,7 @@ export default class GroupController {
   }
 
   /**
-   * Create a new group. Admin only.
+   * @summary Create a new group. Admin only.
    *
    */
   @Example<GroupDetailsResponse>({
@@ -67,7 +67,7 @@ export default class GroupController {
   }
 
   /**
-   * Get list of members of a group (userName). All users can request this.
+   * @summary Get list of members of a group (userName). All users can request this.
    * @param groupId The group's identifier
    * @example groupId 1234
    */
@@ -79,7 +79,7 @@ export default class GroupController {
   }
 
   /**
-   * Add a user to a group. Admin task only.
+   * @summary Add a user to a group. Admin task only.
    * @param groupId The group's identifier
    * @example groupId "1234"
    * @param userId The user's identifier
@@ -101,7 +101,7 @@ export default class GroupController {
   }
 
   /**
-   * Remove a user to a group. Admin task only.
+   * @summary Remove a user to a group. Admin task only.
    * @param groupId The group's identifier
    * @example groupId "1234"
    * @param userId The user's identifier
@@ -123,7 +123,7 @@ export default class GroupController {
   }
 
   /**
-   * Delete a group. Admin task only.
+   * @summary Delete a group. Admin task only.
    * @param groupId The group's identifier
    * @example groupId 1234
    */

api/src/controllers/stp.ts

@@ -0,0 +1,151 @@
+import express from 'express'
+import path from 'path'
+import {
+  Request,
+  Security,
+  Route,
+  Tags,
+  Example,
+  Post,
+  Body,
+  Get,
+  Query
+} from 'tsoa'
+import { ExecutionController } from '.'
+import { PreProgramVars } from '../types'
+import { getTmpFilesFolderPath, makeFilesNamesMap } from '../utils'
+
+interface ExecuteReturnJsonPayload {
+  /**
+   * Location of SAS program
+   * @example "/Public/somefolder/some.file"
+   */
+  _program?: string
+}
+interface ExecuteReturnJsonResponse {
+  status: string
+  log?: string
+  result?: string
+  message?: string
+}
+
+@Security('bearerAuth')
+@Route('SASjsApi/client')
+@Tags('STP')
+export default class STPController {
+  /**
+   * Trigger a SAS program using it's location in the _program parameter.
+   * Enable debugging using the _debug parameter.
+   * Additional URL parameters are turned into SAS macro variables.
+   * Any files provided are placed into the session and
+   * corresponding _WEBIN_XXX variables are created.
+   * @summary Execute Stored Program, return raw content
+   * @query _program Location of SAS program
+   * @example _program "/Public/somefolder/some.file"
+   */
+  @Get('/execute')
+  public async executeReturnRaw(
+    @Request() request: express.Request,
+    @Query() _program: string
+  ): Promise<string> {
+    return executeReturnRaw(request, _program)
+  }
+  /**
+   * Trigger a SAS program using it's location in the _program parameter.
+   * Enable debugging using the _debug parameter.
+   * Additional URL parameters are turned into SAS macro variables.
+   * Any files provided are placed into the session and
+   * corresponding _WEBIN_XXX variables are created.
+   * @summary Execute Stored Program, return JSON
+   * @query _program Location of SAS program
+   * @example _program "/Public/somefolder/some.file"
+   */
+  @Post('/execute')
+  public async executeReturnJson(
+    @Request() request: express.Request,
+    @Body() body: ExecuteReturnJsonPayload,
+    @Query() _program?: string
+  ): Promise<ExecuteReturnJsonResponse> {
+    const program = _program ?? body._program
+    return executeReturnJson(request, program!)
+  }
+}
+
+const executeReturnRaw = async (
+  req: express.Request,
+  _program: string
+): Promise<string> => {
+  const sasCodePath =
+    path
+      .join(getTmpFilesFolderPath(), _program)
+      .replace(new RegExp('/', 'g'), path.sep) + '.sas'
+
+  try {
+    const result = await new ExecutionController().execute(
+      sasCodePath,
+      getPreProgramVariables(req),
+      undefined,
+      undefined,
+      {
+        ...req.query
+      }
+    )
+
+    return result as string
+  } catch (err) {
+    throw {
+      code: 400,
+      status: 'failure',
+      message: 'Job execution failed.',
+      ...(typeof err === 'object' ? err : { details: err })
+    }
+  }
+}
+
+const executeReturnJson = async (
+  req: any,
+  _program: string
+): Promise<ExecuteReturnJsonResponse> => {
+  const sasCodePath =
+    path
+      .join(getTmpFilesFolderPath(), _program)
+      .replace(new RegExp('/', 'g'), path.sep) + '.sas'
+
+  const filesNamesMap = req.files?.length ? makeFilesNamesMap(req.files) : null
+
+  try {
+    const jsonResult: any = await new ExecutionController().execute(
+      sasCodePath,
+      getPreProgramVariables(req),
+      undefined,
+      req.sasSession,
+      { ...req.query, ...req.body },
+      { filesNamesMap: filesNamesMap },
+      true
+    )
+    return {
+      status: 'success',
+      result: jsonResult.result,
+      log: jsonResult.log
+    }
+  } catch (err) {
+    throw {
+      status: 'failure',
+      message: 'Job execution failed.',
+      ...(typeof err === 'object' ? err : { details: err })
+    }
+  }
+}
+
+const getPreProgramVariables = (req: any): PreProgramVars => {
+  const host = req.get('host')
+  const protocol = req.protocol + '://'
+  const { user, accessToken } = req
+  return {
+    username: user.username,
+    userId: user.userId,
+    displayName: user.displayName,
+    serverUrl: protocol + host,
+    accessToken
+  }
+}

api/src/controllers/user.ts

@@ -34,7 +34,7 @@ interface UserDetailsResponse {
 @Tags('User')
 export default class UserController {
   /**
-   * Get list of all users (username, displayname). All users can request this.
+   * @summary Get list of all users (username, displayname). All users can request this.
    *
    */
   @Example<UserResponse[]>([
@@ -55,7 +55,7 @@ export default class UserController {
   }
 
   /**
-   * Create user with the following attributes: UserId, UserName, Password, isAdmin, isActive. Admin only task.
+   * @summary Create user with the following attributes: UserId, UserName, Password, isAdmin, isActive. Admin only task.
    *
    */
   @Example<UserDetailsResponse>({
@@ -73,7 +73,7 @@ export default class UserController {
   }
 
   /**
-   * Get user properties - such as group memberships, userName, displayName.
+   * @summary Get user properties - such as group memberships, userName, displayName.
    * @param userId The user's identifier
    * @example userId 1234
    */
@@ -83,7 +83,7 @@ export default class UserController {
   }
 
   /**
-   * Update user properties - such as displayName. Can be performed either by admins, or the user in question.
+   * @summary Update user properties - such as displayName. Can be performed either by admins, or the user in question.
    * @param userId The user's identifier
    * @example userId "1234"
    */
@@ -103,7 +103,7 @@ export default class UserController {
   }
 
   /**
-   * Delete a user. Can be performed either by admins, or the user in question.
+   * @summary Delete a user. Can be performed either by admins, or the user in question.
    * @param userId The user's identifier
    * @example userId 1234
    */