General Information Guide

Assuming you now that you have the general idea down from the getting started guide, here are further details to aid development

General layout for functions

As of right now, the files are named fairly clearly but they are not directly organized in the repository. We currently have an issue open on github to move the files to different folders for further organization. This will likely happen soon.

Understanding Account Promotion/Creation Flow with Magic Links

• Director generates magic links to promote accounts (maglink.py)
• Scenario 1: Account/Email not in database

• Links is sent to user via email and user creates new account through magic link
• Goes to Authorize.py to create_user to authorize_then_consume
• Essentially, a new account with said permissions is created whenever there is an account promotion

• Scenario 2: Account exists

Call consume.py normally

Understanding Registration

https://github.com/HackRU/lcs/wiki/Using-LCS#the-registration-fsm

Descriptions on each file

authorize.py

What is it for?

authorize.py is used to authorize existing users and also to create users through magic links in the LCS system.

Functions

• authorize - Validates a user given an email and a password. User is then given a token which is returned with its expiry time

• create_user - Given an email, password, and a list of optional fields, create a user and insert into the LCS collection. The goal is to return a complete user, so an empty string is placed wherever a value is not provided

• authorize_then_consume - Authorize user and then consume magic link by calling consume from consume.py. This is called by create_user if user already exists and magic link exists or if a new user is successfully created.

• is_registration_open - Helper function to check if registration is open given timezone and registration dates specified within config

Dependencies

bcrypt, jwt

cal_announce.py

What is it for?

Deals with fetching and updating Slack Announcements and Google Calendar events.

Functions

• slack_announce - Gets slack announcements, cleans up the response and updates or adds new slack announcements in the cache

• google_cal - Interfaces with Google Calendar API and loads the events associated with day-of

Dependencies

pymongo, pickle, googleapiclient

consume.py

What is it for?

Any function that is related to consuming a magic link

Functions

• promotion_link - Update a user’s permissions in the database based on a magic link

• forgot_password_link - Checks if the user exists. If they do, set the password to the new password given by the user.

• consume_url - First checks if a magic link is valid. If it is, check the type of magic link: Forgot password or promotion link. Then, call promotion_link() or forgot_password() accordingly.

Dependencies

bcrypt

maglink.py

What is it for?

Creating magic links of the form 'https://hackru.org/magic/{}' and calling use_sparkpost.py to email them

Functions

• forgot_user - Generates forgotten password magic links for existing users ‘forgot-{}’. Then, it sends an email to the user through sparkpost

• director_link - Generates magic links for one more more users to promote. Sends emails to all the users that need to be promoted.

• do_director_link - Function for directors to promote users through magic links by calling director_link()

• gen_magic_link - Given an email and a valid request and generates magic link by either calling forgot_user for forgot password or do_director_link() for promotion

Dependencies

/NA

qrscan.py

What is it for?

Associating a QR code with a user and then marking them as having attended an event

Functions

• qr_match - Associate a given QR code with a given email

• attend_event - Mark that a user has attended an event.

Dependencies

/NA

read.py

What is it for?

Variety of of read functions for different permission levels

Functions

• tidy_results - Cleans up read results by deleting id and password before returning to user

• public_read - Responsible for performing a public read that can be requested by anyone

• user_read - Function used by LCS user to fetch their information

• organizer_read - Function responsible for performing an organizer query, If insufficient permissions, do user read.

• read_info - Allow for arbitrary mongo query that goes to public read for non-LCS user or organizer read for non-director.

Dependencies

/NA

reimburse.py

What is it for?

Calculating reimbursements for users

Functions

• req_matrix_and_clean - Calls Google API to fetch distances

• req_distance_matrices - Creates distance matrices where one axis represents mode of transportation, while the other represents all unique addresses of hackers

• users_to_reimburse - Creates a table of how much reimbursement of the given users should receive as well as the sum of all the reimbursement to be handed out

• compute_all_reimburse - Function used by director to compute reimbursements for given users

Dependencies

/NA

resume.py

What is it for?

Fetching resumes and storing them to a S3 bucket

Functions

• presign - Generates presign URL to download/upload resume

• exists - checks if a resume already exists for a given user

• resume - Uploads a user’s resume to a S3 bucket

Dependencies

boto3

schemas.py

What is it for?

Wrapper functions to ensure certain conditions are validated/met

Functions

• ensure_schema - Wrapper function used to validate the schema and that the given JSON follows it

• ensure_logged_in_user - Wrapper function used to authorize user using email and an auth token

• ensure_role - Wrapper function used to validate that user has at least 1 role within each subset of the set of roles

Dependencies

jwt, jsonschema

slack.py

What is it for?

Generating slack dm links between users

Functions

• create_error_response - Return error message

• process_slack_error - Separates types of slack errors. User not found/visible or user disabled is a user id issue, otherwise it is a slack API issue

• generate_dm_link - Given other user, ensure they exist, that their and your slack token is present and then generate a slack-dm link by sending a request to slack. Otherwise, return an error message

Dependencies

/NA

use_sparkpost.py

What is it for?

Sending and preparing emails to users or users via sparkpost.

Functions

• list_all_templates - Gets list of templates (form of dictionary) from Sparkpost if and only if the user is an authenticated director

• do_substitutions - Given recipients, links for each recipient, a template, current user, sends out emails with the correct link substituted into the template. This is done by first creating a recipients list which is a list of dictionaries containing the recipient identifier (address) and the data to be substituted in the template (substitution data). Then, the function sends an email to everyone in the recipients list.

• send_to_emails - If the user is not a director, then they are not authorized to send emails. Otherwise, find recipients list, perform the link substitutions by calling do_substiutions(). If any recipients were specified without links or were assumed using the query, then the email is sent to these people with a default template. (Used for promotion magic links to send on mass)

• send_emails - Sends email with the magic link to one person

Dependencies

Sparkpost

util.py

What is it for?

Utility functions regarding databases and sending requests.

Functions

• add_cors_headers - Add headers to allow for cross-origin requests

• cors - Wrapper function that adds cors headers to the return value of the function that is being wrapped

• get_db - Return cached otherwise cache the database uri from the mongo client

• coll - Return database given collection name

Dependencies

/NA

validate.py

What is it for?

Handles updating and validating users in LCS. Basically it checks if changes to a user are valid and then updates them (such as registration state).

Functions

• validate - given a token, ensure that the token is unexpired token of the user with the provided email

• validate_updates - Ensure user is being updated without breaking or violating anything

• • check_registration - Deals with a FSM that essentially checks if edge is traversable. Otherwise, if edge is false, admin must intervene.

• update - Given a user email, a token, and a dictionary of updates, performs all updates the authorised user is permitted to (from updates object onto user with email)

Dependencies

Google maps

waiver.py

What is it for?

For handling uploading and storing a user’s waiver.

Functions

• presign - Used to generate a presign URL to download/upload waiver. The key is user’s email + “.pdf”. By default it is a GET method, but if it is a PUT method, content type is set.

• exists - Checks if waiver already exists for a user

• waiver - Uploads user’s waiver to S3 bucket

Dependencies

boto3