Custom Menu Items

fun Routing.routes() {
    post("api/myapp") {
        // `processPayload` is a helper function that processes payload from Space
        // `KtorRequestAdapter` is an instance of `RequestAdapter` that is
        // used to read HTTP body and headers from the incoming requests.
        //
        // `ktorClient` is an HTTP client that will be used by the application
        // to make all requests to Space.
        //
        // `AppInstanceStorage` is an instance of `SpaceAppInstanceStorage` that stores
        // data on application's client ID, secret, and URL of the Space instance.
        Space.processPayload(KtorRequestAdapter(call), ktorClient, AppInstanceStorage) { payload ->
            when (payload) {
                // ...
                is MenuActionPayload -> {
                    // If the app performs the action on behalf of itself
                    // (the action doesn't require user permissions),
                    // respond with `AppUserActionExecutionResult.Success` or
                    // `AppUserActionExecutionResult.Failure`. For example:
                    //
                    //   doSomething()
                    //   SpaceHttpResponse.RespondWithResult(AppUserActionExecutionResult.Success)

                    // If the app requires user permissions to perform the action
                    // and doesn't have an authorization token yet,
                    // respond with `AppUserActionExecutionResult.AuthCodeFlowRequired`
                    // and require the permissions in this response.

                    // `result` must return some `AppUserActionExecutionResult`.
                    // For example, to perform the action on behalf of the user, it must
                    // return `AppUserActionExecutionResult.AuthCodeFlowRequired`
                    // with required permissions.
                    // If the application already has an authorization token, `result` must
                    // perform the action and return `AppUserActionExecutionResult.Success`.
                    val result = reactToMenuItem(payload)
                    SpaceHttpResponse.RespondWithResult(result)
                }
                // ...
            }
        }
    }
}

// this code extends the example from the previous step
suspend fun ProcessingScope.reactToMenuItem(payload: MenuActionPayload): AppUserActionExecutionResult {
    // Check if we already have a token for this particular user for this app instance.
    // If not, make `permissionRequest` to Space.
    //
    // The implementation of `findRefreshTokenData` may vary depending on how you want to store token data.
    val refreshTokenAndScope = findRefreshTokenData(payload.clientId, payload.userId)
        ?: return permissionsRequest

    // If we have a valid token, make requests to Space.
    // If the token is invalid, make `permissionRequest` to Space.
    val client = clientWithRefreshToken(refreshTokenAndScope.refreshToken, refreshTokenAndScope.scope)
    return try {
        doSomethingInSpace(client, payload)
        AppUserActionExecutionResult.Success(null)
    } catch (e: PermissionDeniedException) {
        permissionsRequest
    } catch (e: RefreshTokenRevokedException) {
        permissionsRequest
    }
}

// The `AppUserActionExecutionResult` class lists possible application responses.
// `AuthCodeFlowRequired` is an app response that requests required permissions.
private val permissionsRequest = AppUserActionExecutionResult.AuthCodeFlowRequired(
    permissionsToRequest = listOf(
        AuthCodeFlowPermissionsRequest(
            // define permission scope: operations you need to perform on behalf of the user
            scope = PermissionScope.build(
                // e.g., the app requires a global permission to view project details
                PermissionScopeElement(
                    GlobalPermissionContextIdentifier,
                    PermissionIdentifier.ViewProjectDetails
                ),
                // a project permission to view issues (in the MY-PRJ project)
                PermissionScopeElement(
                    ProjectPermissionContextIdentifier(ProjectIdentifier.Key("MY-PRJ")),
                    PermissionIdentifier.ViewIssues
                ),
                // and a project permission to update issues (in the MY-PRJ project)
                PermissionScopeElement(
                    ProjectPermissionContextIdentifier(ProjectIdentifier.Key("MY-PRJ")),
                    PermissionIdentifier.UpdateIssues
                )
            ),
            purpose = "Don't ask me why, just give me the permissions"
        )
    )
)