User invite system (#643)

* Add email invitation functionality for new organisation members

- Updated the organisation model to include ChaosEmail for sending invitations.
- Added TODOs for future invite code generation and summary of related UI.

* UI for email invite

* remigrate db, invite model and handler

* add another field in organisation_invite table, according to Kavika's feedback. Fix the backend accordingly.

* frontend the invite page, will now show error log, for example, user already exists etc

* track inviting user's id

* revert api.ts

* fix from passing props to using react-query

* remove try and catch in the invite frontend component

* fix not allow duplicate invites in the backend side

* accept invite if not log in will direct to create account

* invite backend fixes

* invite frontend fixes

---------

Co-authored-by: Peter Nguyen <z5662723@ad.unsw.edu.au>

Author: peternuyn

backend/migrations/20251208090000_organisation_invites.sql

@@ -0,0 +1,15 @@
+CREATE TABLE organisation_invites (
+    id BIGINT PRIMARY KEY,
+    organisation_id BIGINT NOT NULL REFERENCES organisations(id) ON DELETE CASCADE,
+    code TEXT NOT NULL UNIQUE,
+    email TEXT NOT NULL,
+    expires_at TIMESTAMPTZ NOT NULL,
+    used_at TIMESTAMPTZ,
+    used_by BIGINT REFERENCES users(id) ON DELETE SET NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    invited_by_user_id BIGINT REFERENCES users(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IDX_organisation_invites_code ON organisation_invites(code);
+CREATE INDEX IDX_organisation_invites_organisation_id ON organisation_invites(organisation_id);
+CREATE INDEX IDX_organisation_invites_email ON organisation_invites(email);

backend/server/src/handler/invite.rs

@@ -0,0 +1,87 @@
+use crate::models::app::AppMessage;
+use crate::models::auth::AuthUser;
+use crate::models::error::ChaosError;
+use crate::models::invite::Invite;
+use crate::models::organisation::Organisation;
+use crate::models::transaction::DBTransaction;
+use crate::models::user::User;
+use axum::extract::Path;
+use axum::response::IntoResponse;
+use sqlx::query;
+use std::ops::DerefMut;
+
+
+/// Handler for invite-related HTTP requests.
+pub struct InviteHandler;
+
+impl InviteHandler {
+    /// Gets invite details for a given invite code.
+    ///
+    /// # Arguments
+    ///
+    /// * `transaction` - Database transaction
+    /// * `code` - Invite code
+    ///
+    /// # Returns
+    ///
+    /// * `Result<impl IntoResponse, ChaosError>` - Invite details or error
+    pub async fn get(
+        mut transaction: DBTransaction<'_>,
+        Path(code): Path<String>,
+    ) -> Result<impl IntoResponse, ChaosError> {
+        let invite = Invite::get_by_code(&code, &mut transaction.tx).await?;
+
+        transaction.tx.commit().await?;
+        Ok(AppMessage::OkMessage(invite))
+    }
+
+    /// Accepts an invite for the current authenticated user.
+    ///
+    /// Validates the invite is not expired/used, then marks it as used.
+    ///
+    /// # Arguments
+    ///
+    /// * `transaction` - Database transaction
+    /// * `code` - Invite code
+    /// * `user` - Authenticated user
+    ///
+    /// # Returns
+    ///
+    /// * `Result<impl IntoResponse, ChaosError>` - Success message or error
+    pub async fn use_invite(
+        mut transaction: DBTransaction<'_>,
+        Path(code): Path<String>,
+        auth_user: AuthUser,
+    ) -> Result<impl IntoResponse, ChaosError> {
+        let invite = Invite::get_by_code(&code, &mut transaction.tx).await?;
+
+        // Ensure the invite can only be accepted by the account whose email matches the invite email.
+        // This prevents someone from accepting an invite intended for a different email address.
+        let user = User::get(auth_user.user_id, &mut transaction.tx).await?;
+
+        if user.email != invite.email {
+            return Err(ChaosError::BadRequestWithMessage(
+                "Invite was sent for a different email address".to_string(),
+            ));
+        }
+
+        // Validate the invite is not already used or expired.
+        if invite.used {
+            return Err(ChaosError::BadRequestWithMessage("Invite already used".to_string()));
+        }
+        if invite.expired {
+            return Err(ChaosError::BadRequestWithMessage("Invite expired".to_string()));
+        }
+
+        // Add the user to the organisation.
+        Organisation::add_user(invite.organisation_id, auth_user.user_id, &mut transaction.tx).await?;
+
+        // Mark the invite as used.
+        Invite::mark_used(&code, auth_user.user_id, &mut transaction.tx).await?;
+
+        transaction.tx.commit().await?;
+        Ok(AppMessage::OkMessage("Invite accepted successfully"))
+    }
+
+    
+}

backend/server/src/handler/mod.rs

@@ -11,6 +11,7 @@
 //! - `email_template`: Processes email template requests
 //! - `offer`: Handles offer-related requests
 //! - `organisation`: Processes organisation-related requests
+//! - `invite`: Handles invite-related requests
 //! - `question`: Handles question-related requests
 //! - `rating`: Processes rating-related requests
 //! - `role`: Handles role-related requests
@@ -23,6 +24,7 @@ pub mod campaign;
 pub mod email_template;
 pub mod offer;
 pub mod organisation;
+pub mod invite;
 pub mod question;
 pub mod rating;
 pub mod role;

backend/server/src/handler/organisation.rs

@@ -359,14 +359,22 @@ impl OrganisationHandler {
     pub async fn invite_user(
         mut transaction: DBTransaction<'_>,
         Path(id): Path<i64>,
-        _admin: OrganisationAdmin,
-        State(state): State<AppState>,
+        admin: OrganisationAdmin,
+        State(mut state): State<AppState>,
         Json(request_body): Json<MemberToInvite>,
     ) -> Result<impl IntoResponse, ChaosError> {
-        Organisation::invite_user(id, request_body.email, state.email_credentials, &mut transaction.tx).await?;
+        let invite_code = Organisation::invite_user(
+            id,
+            admin.user_id,
+            request_body.email,
+            state.email_credentials.clone(),
+            &mut state.snowflake_generator,
+            &mut transaction.tx,
+        )
+        .await?;
 
         transaction.tx.commit().await?;
-        Ok(AppMessage::OkMessage("Successfully invited user to organisation"))
+        Ok(AppMessage::OkMessage(invite_code))
     }
 
     /// Updates an organisation's logo.

backend/server/src/models/app.rs

@@ -8,6 +8,7 @@ use crate::handler::organisation::OrganisationHandler;
 use crate::handler::question::QuestionHandler;
 use crate::handler::rating::RatingHandler;
 use crate::handler::role::RoleHandler;
+use crate::handler::invite::InviteHandler;
 use crate::handler::user::UserHandler;
 use crate::models::email::{ChaosEmail, EmailCredentials};
 use crate::models::error::ChaosError;
@@ -28,6 +29,7 @@ use serde::Serialize;
 use tower_http::cors::CorsLayer;
 use crate::service::oauth2::build_oauth_client;
 
+
 #[derive(Serialize)]
 pub enum AppMessage<T: Serialize> {
     OkMessage(T),
@@ -437,6 +439,17 @@ pub async fn app() -> Result<Router, ChaosError> {
             "/api/v1/offer/:offer_id/send",
             post(OfferHandler::send_offer),
         )
+
+        // Invite routes
+        // - GET  /api/v1/invite/:code  -> invite details
+        // - POST /api/v1/invite/:code  -> accept invite
+        .route(
+            "/api/v1/invite/:code", get(InviteHandler::get).post(InviteHandler::use_invite)
+        )
+
+        
+
+        
         .layer(cors)
         .with_state(state))
 }

backend/server/src/models/invite.rs

@@ -0,0 +1,146 @@
+use crate::models::error::ChaosError;
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::{Postgres, Transaction};
+use std::ops::DerefMut;
+
+/// Represents an organisation invite.
+#[derive(Deserialize, Serialize, sqlx::FromRow, Clone, Debug)]
+pub struct Invite {
+    /// Unique identifier for the invite
+    #[serde(serialize_with = "crate::models::serde_string::serialize")]
+    #[serde(deserialize_with = "crate::models::serde_string::deserialize")]
+    pub id: i64,
+    /// Unique invite code (used by invite URL)
+    pub code: String,
+    /// Organisation being invited to
+    #[serde(serialize_with = "crate::models::serde_string::serialize")]
+    #[serde(deserialize_with = "crate::models::serde_string::deserialize")]
+    pub organisation_id: i64,
+    /// Email address the invite was sent to
+    pub email: String,
+    /// When the invite expires
+    pub expires_at: DateTime<Utc>,
+    /// When the invite was used (if used)
+    pub used_at: Option<DateTime<Utc>>,
+    /// User who used the invite (if used)
+    #[serde(serialize_with = "crate::models::serde_string::serialize_option")]
+    #[serde(deserialize_with = "crate::models::serde_string::deserialize_option")]
+    pub used_by: Option<i64>,
+    /// When the invite was created
+    pub created_at: DateTime<Utc>,
+    /// ID of the user that invited the member to the organisation
+    #[serde(serialize_with = "crate::models::serde_string::serialize_option")]
+    #[serde(deserialize_with = "crate::models::serde_string::deserialize_option")]
+    pub invited_by_user_id: Option<i64>,
+}
+
+/// Response payload for invite details expected by the frontend.
+#[derive(Serialize)]
+pub struct InviteDetails {
+    #[serde(serialize_with = "crate::models::serde_string::serialize")]
+    pub id: i64,
+    pub code: String,
+    #[serde(serialize_with = "crate::models::serde_string::serialize")]
+    pub organisation_id: i64,
+    pub organisation_name: String,
+    pub email: String,
+    pub expires_at: DateTime<Utc>,
+    pub used: bool,
+    pub expired: bool,
+    /// ID of the user that invited the member to the organisation
+    #[serde(serialize_with = "crate::models::serde_string::serialize_option")]
+    #[serde(deserialize_with = "crate::models::serde_string::deserialize_option")]
+    pub invited_by_user_id: Option<i64>
+}
+
+impl Invite {
+    /// Fetches an invite by its code.
+    ///
+    /// # Arguments
+    ///
+    /// * `code` - Invite code
+    /// * `transaction` - Database transaction to use
+    ///
+    /// # Returns
+    ///
+    /// * `Result<Invite, ChaosError>` - Invite row or error
+    pub async fn get_by_code(
+        code: &str,
+        transaction: &mut Transaction<'_, Postgres>,
+    ) -> Result<InviteDetails, ChaosError> {
+        let invite = sqlx::query_as!(
+            InviteDetails,
+            r#"
+                SELECT
+                    oi.id,
+                    code,
+                    organisation_id,
+                    o.name AS organisation_name,
+                    email,
+                    expires_at,
+                    used_at IS NOT NULL AS "used!: bool",
+                    expires_at <= NOW() AS "expired!: bool",
+                    invited_by_user_id
+                FROM organisation_invites oi
+                JOIN organisations o ON o.id = oi.organisation_id
+                WHERE code = $1 AND used_at IS NULL AND expires_at > NOW()
+            "#,
+            code
+        )
+        .fetch_one(transaction.deref_mut())
+        .await?;
+
+        Ok(invite)
+    }
+
+    /// Marks an invite as used by a user.
+    ///
+    /// # Arguments
+    ///
+    /// * `code` - Invite code
+    /// * `user_id` - User redeeming the invite
+    /// * `transaction` - Database transaction to use
+    ///
+    /// # Returns
+    ///
+    /// * `Result<(), ChaosError>` - Ok on success
+    pub async fn mark_used(
+        code: &str,
+        user_id: i64,
+        transaction: &mut Transaction<'_, Postgres>,
+    ) -> Result<(), ChaosError> {
+        let _ = sqlx::query!(
+            r#"
+                UPDATE organisation_invites
+                SET used_at = $1, used_by = $2
+                WHERE code = $3 AND used_at IS NULL AND expires_at > NOW()
+                RETURNING id
+            "#,
+            Utc::now(),
+            user_id,
+            code,
+        )
+        .fetch_one(transaction.deref_mut())
+        .await?;
+
+        Ok(())
+    }
+
+    /// Deletes an invite by code.
+    pub async fn delete_by_code(
+        code: &str,
+        transaction: &mut Transaction<'_, Postgres>,
+    ) -> Result<(), ChaosError> {
+        let _ = sqlx::query!(
+            "DELETE FROM organisation_invites WHERE code = $1 RETURNING id",
+            code
+        )
+        .fetch_one(transaction.deref_mut())
+        .await?;
+
+        Ok(())
+    }
+
+
+}

backend/server/src/models/mod.rs

@@ -16,6 +16,7 @@ pub mod serde_string;
 pub mod email;
 pub mod email_template;
 pub mod error;
+pub mod invite;
 pub mod offer;
 pub mod organisation;
 pub mod question;