fix: admin grant credits

Author: think-in-universe

crates/api/src/routes/admin.rs

@@ -241,6 +241,87 @@ pub async fn list_users(
     }))
 }
 
+/// Admin request to grant credits to a user (nano-USD).
+#[derive(Debug, Deserialize, Serialize, utoipa::ToSchema)]
+pub struct AdminGrantCreditsRequest {
+    /// Target user id
+    pub user_id: Uuid,
+    /// Grant amount in nano-USD (must be positive; 1_000_000_000 = $1).
+    pub amount_nano_usd: i64,
+    /// Optional reason for the grant (stored as reference_id in credit_transactions).
+    #[serde(default)]
+    pub reason: Option<String>,
+}
+
+/// Admin response after granting credits.
+#[derive(Debug, Deserialize, Serialize, utoipa::ToSchema)]
+pub struct AdminGrantCreditsResponse {
+    /// New purchased credits balance for the user (nano-USD).
+    pub new_balance_nano_usd: i64,
+}
+
+/// Admin endpoint: Grant credits to a user (manual/admin adjustment).
+#[utoipa::path(
+    post,
+    path = "/v1/admin/credits",
+    tag = "Admin",
+    request_body = AdminGrantCreditsRequest,
+    responses(
+        (status = 200, description = "Credits granted successfully", body = AdminGrantCreditsResponse),
+        (status = 400, description = "Invalid request", body = crate::error::ApiErrorResponse),
+        (status = 401, description = "Unauthorized", body = crate::error::ApiErrorResponse),
+        (status = 403, description = "Forbidden - Admin access required", body = crate::error::ApiErrorResponse),
+        (status = 500, description = "Internal server error", body = crate::error::ApiErrorResponse)
+    ),
+    security(
+        ("session_token" = [])
+    )
+)]
+pub async fn admin_grant_credits(
+    State(app_state): State<AppState>,
+    Json(request): Json<AdminGrantCreditsRequest>,
+) -> Result<Json<AdminGrantCreditsResponse>, ApiError> {
+    if request.amount_nano_usd <= 0 {
+        return Err(ApiError::bad_request(
+            "amount_nano_usd must be positive".to_string(),
+        ));
+    }
+
+    let user_id = UserId(request.user_id);
+    tracing::info!(
+        "Admin: Granting credits to user_id={}, amount_nano_usd={}, reason={:?}",
+        user_id,
+        request.amount_nano_usd,
+        request.reason
+    );
+
+    let new_balance = app_state
+        .subscription_service
+        .admin_grant_credits(user_id, request.amount_nano_usd, request.reason.clone())
+        .await
+        .map_err(|e| match e {
+            services::subscription::ports::SubscriptionError::InvalidCredits(msg) => {
+                ApiError::bad_request(msg)
+            }
+            services::subscription::ports::SubscriptionError::DatabaseError(msg) => {
+                tracing::error!(error = ?msg, "Database error granting credits");
+                ApiError::internal_server_error("Failed to grant credits")
+            }
+            services::subscription::ports::SubscriptionError::InternalError(msg) => {
+                tracing::error!(error = ?msg, "Internal error granting credits");
+                ApiError::internal_server_error("Failed to grant credits")
+            }
+            other => {
+                tracing::error!(error = ?other, "Unexpected error granting credits");
+                ApiError::internal_server_error("Failed to grant credits")
+            }
+        })?;
+
+    Ok(Json(AdminGrantCreditsResponse {
+        new_balance_nano_usd: new_balance,
+    }))
+}
+
 /// Implementation used by bi_list_users only (BI endpoint).
 async fn list_users_bi_impl(
     app_state: &AppState,
@@ -2449,6 +2530,7 @@ pub fn create_admin_router() -> Router<AppState> {
         .route("/models", get(list_models).patch(batch_upsert_models))
         .route("/models/{model_id}", delete(delete_model))
         .route("/vpc/revoke", post(revoke_vpc_credentials))
+        .route("/credits", post(admin_grant_credits))
         .route(
             "/configs",
             get(get_system_configs_admin).patch(upsert_system_configs),

crates/api/tests/admin_tests.rs

@@ -1,6 +1,7 @@
 mod common;
 
 use common::{create_test_server, create_test_server_and_db, mock_login};
+use serde_json::json;
 use services::user::ports::UserRepository;
 use uuid::Uuid;
 
@@ -131,6 +132,112 @@ async fn test_revoke_vpc_credentials_with_non_admin_account() {
     assert_eq!(error, Some("Admin access required"));
 }
 
+#[tokio::test]
+async fn test_admin_grant_credits_with_admin_account() {
+    let (server, db) = create_test_server_and_db(common::TestServerConfig::default()).await;
+
+    // Create a regular user
+    let user_email = "credits_user@example.com";
+    let user_token = mock_login(&server, user_email).await;
+    let users_repo = db.user_repository();
+    let user = users_repo
+        .get_user_by_email(user_email)
+        .await
+        .expect("get_user_by_email")
+        .expect("user should exist");
+
+    // Admin token
+    let admin_email = "credits_admin@admin.org";
+    let admin_token = mock_login(&server, admin_email).await;
+
+    // Grant 2 USD worth of credits (2_000_000_000 nano-USD)
+    let grant_body = json!({
+        "user_id": user.id,
+        "amount_nano_usd": 2_000_000_000_i64,
+        "reason": "test admin grant"
+    });
+
+    let response = server
+        .post("/v1/admin/credits")
+        .add_header(
+            http::HeaderName::from_static("authorization"),
+            http::HeaderValue::from_str(&format!("Bearer {admin_token}")).unwrap(),
+        )
+        .add_header(
+            http::HeaderName::from_static("content-type"),
+            http::HeaderValue::from_static("application/json"),
+        )
+        .json(&grant_body)
+        .await;
+
+    assert_eq!(
+        response.status_code(),
+        200,
+        "Admin should be able to grant credits"
+    );
+
+    let body: serde_json::Value = response.json();
+    let new_balance = body
+        .get("new_balance_nano_usd")
+        .and_then(|v| v.as_i64())
+        .expect("new_balance_nano_usd should be present");
+    assert_eq!(new_balance, 2_000_000_000_i64);
+
+    // Verify that the endpoint is protected (regular user cannot call it successfully)
+    let response_non_admin = server
+        .post("/v1/admin/credits")
+        .add_header(
+            http::HeaderName::from_static("authorization"),
+            http::HeaderValue::from_str(&format!("Bearer {user_token}")).unwrap(),
+        )
+        .add_header(
+            http::HeaderName::from_static("content-type"),
+            http::HeaderValue::from_static("application/json"),
+        )
+        .json(&grant_body)
+        .await;
+
+    assert_eq!(
+        response_non_admin.status_code(),
+        403,
+        "Non-admin should receive 403 Forbidden when trying to grant credits"
+    );
+    let body_non_admin: serde_json::Value = response_non_admin.json();
+    let error = body_non_admin.get("message").and_then(|v| v.as_str());
+    assert_eq!(error, Some("Admin access required"));
+}
+
+#[tokio::test]
+async fn test_admin_grant_credits_validation() {
+    let server = create_test_server().await;
+
+    let admin_email = "credits_admin_validation@admin.org";
+    let admin_token = mock_login(&server, admin_email).await;
+
+    let body = json!({
+        "user_id": "00000000-0000-4000-8000-000000000000",
+        "amount_nano_usd": 0
+    });
+
+    let response = server
+        .post("/v1/admin/credits")
+        .add_header(
+            http::HeaderName::from_static("authorization"),
+            http::HeaderValue::from_str(&format!("Bearer {admin_token}")).unwrap(),
+        )
+        .add_header(
+            http::HeaderName::from_static("content-type"),
+            http::HeaderValue::from_static("application/json"),
+        )
+        .json(&body)
+        .await;
+
+    assert_eq!(response.status_code(), 400);
+    let body_json: serde_json::Value = response.json();
+    let message = body_json.get("message").and_then(|v| v.as_str());
+    assert_eq!(message, Some("amount_nano_usd must be positive"));
+}
+
 /// Admin list instances sanitizes dashboard_url by stripping query params, fragment, and userinfo.
 #[tokio::test]
 async fn test_admin_agents_instances_sanitizes_dashboard_url() {

crates/database/src/repositories/credits_repository.rs

@@ -78,4 +78,22 @@ impl CreditsRepository for PostgresCreditsRepository {
             }
         }
     }
+
+    async fn record_grant(
+        &self,
+        txn: &tokio_postgres::Transaction<'_>,
+        user_id: UserId,
+        amount: i64,
+        reason: Option<String>,
+    ) -> anyhow::Result<()> {
+        txn.execute(
+            r#"
+            INSERT INTO credit_transactions (user_id, amount, type, reference_id)
+            VALUES ($1, $2, 'grant', $3)
+            "#,
+            &[&user_id, &amount, &reason],
+        )
+        .await?;
+        Ok(())
+    }
 }

crates/services/src/subscription/ports.rs

@@ -233,6 +233,15 @@ pub trait CreditsRepository: Send + Sync {
         amount: i64,
         reference_id: &str,
     ) -> anyhow::Result<bool>;
+
+    /// Record an admin grant transaction (for manual/admin adjustments).
+    async fn record_grant(
+        &self,
+        txn: &tokio_postgres::Transaction<'_>,
+        user_id: UserId,
+        amount: i64,
+        reason: Option<String>,
+    ) -> anyhow::Result<()>;
 }
 
 /// Repository trait for payment webhook events
@@ -365,6 +374,15 @@ pub trait SubscriptionService: Send + Sync {
 
     /// Get user's credits: balance, used in period, effective max.
     async fn get_credits(&self, user_id: UserId) -> Result<CreditsSummary, SubscriptionError>;
+
+    /// Admin-only: grant credits (nano-USD) directly to a user.
+    /// Records a 'grant' transaction and updates user_credits balance.
+    async fn admin_grant_credits(
+        &self,
+        user_id: UserId,
+        amount_nano_usd: i64,
+        reason: Option<String>,
+    ) -> Result<i64, SubscriptionError>;
 }
 
 /// Summary of user's credits (balance, used, effective limit).

crates/services/src/subscription/service.rs

@@ -1683,4 +1683,47 @@ impl SubscriptionService for SubscriptionServiceImpl {
             effective_max_credits,
         })
     }
+
+    async fn admin_grant_credits(
+        &self,
+        user_id: UserId,
+        amount_nano_usd: i64,
+        reason: Option<String>,
+    ) -> Result<i64, SubscriptionError> {
+        if amount_nano_usd <= 0 {
+            return Err(SubscriptionError::InvalidCredits(
+                "grant amount must be positive".to_string(),
+            ));
+        }
+
+        let mut client = self
+            .db_pool
+            .get()
+            .await
+            .map_err(|e| SubscriptionError::DatabaseError(e.to_string()))?;
+        let txn = client
+            .transaction()
+            .await
+            .map_err(|e| SubscriptionError::DatabaseError(e.to_string()))?;
+
+        self.credits_repo
+            .record_grant(&txn, user_id, amount_nano_usd, reason)
+            .await
+            .map_err(|e| SubscriptionError::DatabaseError(e.to_string()))?;
+
+        let new_balance = self
+            .credits_repo
+            .add_credits(&txn, user_id, amount_nano_usd)
+            .await
+            .map_err(|e| SubscriptionError::DatabaseError(e.to_string()))?;
+
+        txn.commit()
+            .await
+            .map_err(|e| SubscriptionError::DatabaseError(e.to_string()))?;
+
+        // Invalidate cache so future checks see updated purchased balance
+        self.invalidate_credit_limit_cache(user_id).await;
+
+        Ok(new_balance)
+    }
 }