fix(billing): auto-link accounts to Hyperline customer (close SCR-68 gap) (#19)

qdequele · web-flow · commit 20bf9327f3cf · 2026-05-18T22:26:00.000+02:00
SCR-68 migrated billing from Stripe to Hyperline but never wired up
customer creation — signup, the portal handler, and ops tooling all
assumed someone would backfill manually. Existing accounts (e.g.
internal dogfooding teams created pre-migration) ended up stranded
with hyperline_customer_id IS NULL and a permanent 404 from
GET /account/billing/portal, with no self-serve path forward.

This commit:

- HyperlineClient::create_customer + find_customer_by_external_id —
  POST /v1/customers and a GET filter that recovers customers
  orphaned by a partial link (network drop between Hyperline POST
  and our DB UPDATE).

- GET /account/billing/portal lazy-links on first hit when
  hyperline_customer_id IS NULL. Reuses an existing Hyperline
  customer with the same external_id (= accounts.id) if one is
  found, otherwise creates. The UPDATE uses COALESCE so concurrent
  linkers converge on a single id.

- POST /auth/signup eager-links via tokio::spawn — fire-and-forget
  so the signup latency budget is unaffected. The lazy-create path
  is the backstop if the spawn task fails.

- bins/scrapix-api/src/bin/backfill_hyperline_customers.rs — one-shot
  ops binary for the existing NULL rows. Idempotent on re-run (looks
  up by external_id first), per-account logging so a single bad row
  doesn't abort the batch.
diff --git a/bins/scrapix-api/src/auth/handlers/auth.rs b/bins/scrapix-api/src/auth/handlers/auth.rs
@@ -7,8 +7,9 @@ use axum_extra::extract::CookieJar;
 use sha2::{Digest, Sha256};
 use sqlx::Row;
 use std::sync::Arc;
-use tracing::info;
+use tracing::{info, warn};
 
+use super::billing::link_account_to_hyperline;
 use super::{
     build_session_cookie, clear_session_cookie, err, AccountResponse, ApiError, ErrorBody,
     ForgotPasswordRequest, LoginRequest, MessageResponse, ResetPasswordRequest, SignupRequest,
@@ -156,6 +157,27 @@ pub(crate) async fn signup(
 
     info!(user_id = %user_id, email = %req.email, "New user signed up");
 
+    // Best-effort: create the Hyperline customer in the background so the
+    // first GET /account/billing/portal call doesn't pay the latency. If
+    // this fails (Hyperline outage, etc.), the portal handler's
+    // lazy-create path will retry on next click.
+    if let Some(client) = state.hyperline_client.clone() {
+        let pool = state.pool.clone();
+        let name = account_name.clone();
+        let email = req.email.clone();
+        tokio::spawn(async move {
+            if let Err(e) =
+                link_account_to_hyperline(&pool, &client, account_id, &name, &email).await
+            {
+                warn!(
+                    account_id = %account_id,
+                    error = %e,
+                    "hyperline eager-link on signup failed — will retry lazily on first portal click"
+                );
+            }
+        });
+    }
+
     // Auto-accept pending invites for this email
     let pending_invites = sqlx::query(
         "SELECT id, account_id, role FROM account_invites \
diff --git a/bins/scrapix-api/src/auth/handlers/billing.rs b/bins/scrapix-api/src/auth/handlers/billing.rs
@@ -3,7 +3,8 @@ use axum::{
     http::StatusCode,
     Json,
 };
-use sqlx::Row;
+use scrapix_billing_hyperline::HyperlineClient;
+use sqlx::{PgPool, Row};
 use std::sync::Arc;
 use tracing::{error, info};
 
@@ -14,6 +15,87 @@ use super::{
 };
 use crate::auth::{AuthState, AuthenticatedUser};
 
+/// Lazily link an account to a Hyperline customer.
+///
+/// Looks up `(account_name, owner_email)`, queries Hyperline for an
+/// existing customer with `external_id = account_id` (recovers from
+/// crashes that orphaned a customer mid-link), creates one if absent,
+/// then `UPDATE accounts SET hyperline_customer_id = COALESCE(...)` so
+/// concurrent linkers converge on a single value.
+///
+/// Returns the linked customer id. Network/auth failures bubble up;
+/// the caller decides which HTTP status to map to.
+pub(crate) async fn link_account_to_hyperline(
+    pool: &PgPool,
+    client: &HyperlineClient,
+    account_id: uuid::Uuid,
+    account_name: &str,
+    owner_email: &str,
+) -> Result<String, scrapix_billing_hyperline::HyperlineError> {
+    let external_id = account_id.to_string();
+
+    let customer = match client.find_customer_by_external_id(&external_id).await? {
+        Some(existing) => {
+            info!(
+                account_id = %account_id,
+                customer_id = %existing.id,
+                "hyperline: recovered orphaned customer by external_id"
+            );
+            existing
+        }
+        None => {
+            let created = client
+                .create_customer(&external_id, account_name, owner_email)
+                .await?;
+            info!(
+                account_id = %account_id,
+                customer_id = %created.id,
+                "hyperline: created customer"
+            );
+            created
+        }
+    };
+
+    // COALESCE handles the race where another request linked first; we
+    // adopt whatever id won and discard our just-created one (it stays
+    // in Hyperline as an orphan, but `find_customer_by_external_id`
+    // will reuse it on any future link attempt for this account).
+    let linked_id: String = sqlx::query_scalar(
+        "UPDATE accounts \
+         SET hyperline_customer_id = COALESCE(hyperline_customer_id, $1) \
+         WHERE id = $2 RETURNING hyperline_customer_id",
+    )
+    .bind(&customer.id)
+    .bind(account_id)
+    .fetch_one(pool)
+    .await
+    .map_err(|e| scrapix_billing_hyperline::HyperlineError::InvalidConfig(format!("db: {e}")))?;
+
+    Ok(linked_id)
+}
+
+/// Owner email for an account — used as the Hyperline `email` field
+/// on lazy customer creation. Picks the oldest 'owner' membership so
+/// the result is stable across reruns.
+pub(crate) async fn account_owner_email(
+    pool: &PgPool,
+    account_id: uuid::Uuid,
+) -> Result<Option<(String, String)>, sqlx::Error> {
+    let row = sqlx::query(
+        "SELECT a.name AS account_name, u.email AS owner_email \
+         FROM accounts a \
+         JOIN account_members m ON m.account_id = a.id \
+         JOIN users u ON u.id = m.user_id \
+         WHERE a.id = $1 AND m.role = 'owner' \
+         ORDER BY m.joined_at ASC \
+         LIMIT 1",
+    )
+    .bind(account_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|r| (r.get("account_name"), r.get("owner_email"))))
+}
+
 #[utoipa::path(
     get,
     path = "/account/billing",
@@ -142,12 +224,46 @@ pub(crate) async fn get_billing_portal(
             })?
             .flatten();
 
-    let Some(customer_id) = customer_id else {
-        return Err(err(
-            StatusCode::NOT_FOUND,
-            "Account is not linked to Hyperline yet",
-            "not_linked",
-        ));
+    let customer_id = match customer_id {
+        Some(id) => id,
+        None => {
+            // First portal request for this account — lazy-link to Hyperline.
+            // Closes the gap left by SCR-68 (no automated customer creation):
+            // accounts created before the migration, or whose eager-create at
+            // signup failed, would otherwise be stuck with a 404 forever.
+            let Some((account_name, owner_email)) = account_owner_email(&state.pool, account_id)
+                .await
+                .map_err(|e| {
+                    error!(account_id = %account_id, error = %e, "owner lookup failed");
+                    err(
+                        StatusCode::INTERNAL_SERVER_ERROR,
+                        "Database error",
+                        "internal_error",
+                    )
+                })?
+            else {
+                return Err(err(
+                    StatusCode::NOT_FOUND,
+                    "Account has no owner — cannot link to Hyperline",
+                    "no_owner",
+                ));
+            };
+
+            link_account_to_hyperline(&state.pool, client, account_id, &account_name, &owner_email)
+                .await
+                .map_err(|e| {
+                    error!(
+                        account_id = %account_id,
+                        error = %e,
+                        "hyperline lazy-link failed"
+                    );
+                    err(
+                        StatusCode::BAD_GATEWAY,
+                        "Failed to link account to Hyperline",
+                        "hyperline_upstream",
+                    )
+                })?
+        }
     };
 
     match client.get_portal_url(&customer_id).await {
diff --git a/bins/scrapix-api/src/bin/backfill_hyperline_customers.rs b/bins/scrapix-api/src/bin/backfill_hyperline_customers.rs
@@ -0,0 +1,147 @@
+//! Backfill `accounts.hyperline_customer_id` for rows that survived the
+//! SCR-68 Stripe → Hyperline migration with NULL.
+//!
+//! Walks every account where `hyperline_customer_id IS NULL`, looks up
+//! the oldest 'owner' membership for `(name, email)`, and either reuses
+//! an existing Hyperline customer (matched by `external_id =
+//! accounts.id`) or creates a new one — then writes the id back.
+//!
+//! Safe to re-run: each step is idempotent. Failures are logged per
+//! account and the loop continues; rerun to retry only the survivors.
+//!
+//! ```sh
+//! DATABASE_URL=postgres://… \
+//! HYPERLINE_API_KEY=prod_… \
+//!   cargo run -p scrapix-api --bin backfill_hyperline_customers
+//! ```
+
+use std::error::Error;
+
+use scrapix_billing_hyperline::HyperlineClient;
+use sqlx::{postgres::PgPoolOptions, PgPool, Row};
+use tracing::{error, info, warn};
+use uuid::Uuid;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
+        )
+        .init();
+
+    let database_url = std::env::var("DATABASE_URL")?;
+    let url = if !database_url.contains("sslmode=") {
+        let sep = if database_url.contains('?') { "&" } else { "?" };
+        format!("{database_url}{sep}sslmode=require")
+    } else {
+        database_url
+    };
+    let pool = PgPoolOptions::new()
+        .max_connections(2)
+        .connect(&url)
+        .await?;
+
+    let client = HyperlineClient::from_env()?;
+    let target = if client.config().is_sandbox() {
+        "sandbox"
+    } else {
+        "PRODUCTION"
+    };
+    info!("Backfilling Hyperline customers into {target}…");
+
+    // We page through accounts; new ones get linked as the loop runs so
+    // restarting from the top each iteration would be wasteful. Capture
+    // the snapshot once and walk it.
+    let rows = sqlx::query(
+        "SELECT a.id AS account_id, a.name AS account_name, u.email AS owner_email \
+         FROM accounts a \
+         JOIN account_members m ON m.account_id = a.id AND m.role = 'owner' \
+         JOIN users u ON u.id = m.user_id \
+         WHERE a.hyperline_customer_id IS NULL \
+         GROUP BY a.id, a.name, u.email, m.joined_at \
+         ORDER BY a.id, m.joined_at ASC",
+    )
+    .fetch_all(&pool)
+    .await?;
+
+    // GROUP BY + ORDER BY gives duplicates per account if multiple
+    // owners. Dedup by account_id, keeping first (= oldest owner).
+    let mut seen = std::collections::HashSet::new();
+    let mut targets: Vec<(Uuid, String, String)> = Vec::new();
+    for row in rows {
+        let id: Uuid = row.get("account_id");
+        if !seen.insert(id) {
+            continue;
+        }
+        targets.push((id, row.get("account_name"), row.get("owner_email")));
+    }
+
+    info!("Found {} unlinked account(s)", targets.len());
+
+    let mut linked = 0usize;
+    let mut reused = 0usize;
+    let mut failed = 0usize;
+
+    for (account_id, account_name, owner_email) in targets {
+        match link_one(&pool, &client, account_id, &account_name, &owner_email).await {
+            Ok(LinkOutcome::Created) => {
+                linked += 1;
+                info!(account_id = %account_id, "linked (created in Hyperline)");
+            }
+            Ok(LinkOutcome::Reused) => {
+                reused += 1;
+                info!(account_id = %account_id, "linked (reused existing Hyperline customer)");
+            }
+            Err(e) => {
+                failed += 1;
+                error!(account_id = %account_id, error = %e, "link failed");
+            }
+        }
+    }
+
+    info!("Done. created={linked} reused={reused} failed={failed}");
+    if failed > 0 {
+        warn!("{failed} account(s) still unlinked — rerun after addressing the root cause");
+        std::process::exit(1);
+    }
+    Ok(())
+}
+
+enum LinkOutcome {
+    Created,
+    Reused,
+}
+
+async fn link_one(
+    pool: &PgPool,
+    client: &HyperlineClient,
+    account_id: Uuid,
+    account_name: &str,
+    owner_email: &str,
+) -> Result<LinkOutcome, Box<dyn Error>> {
+    let external_id = account_id.to_string();
+
+    let (customer_id, outcome) = match client.find_customer_by_external_id(&external_id).await? {
+        Some(existing) => (existing.id, LinkOutcome::Reused),
+        None => {
+            let created = client
+                .create_customer(&external_id, account_name, owner_email)
+                .await?;
+            (created.id, LinkOutcome::Created)
+        }
+    };
+
+    sqlx::query(
+        "UPDATE accounts \
+         SET hyperline_customer_id = COALESCE(hyperline_customer_id, $1) \
+         WHERE id = $2",
+    )
+    .bind(&customer_id)
+    .bind(account_id)
+    .execute(pool)
+    .await?;
+
+    Ok(outcome)
+}
diff --git a/crates/scrapix-billing-hyperline/src/client.rs b/crates/scrapix-billing-hyperline/src/client.rs
@@ -200,6 +200,45 @@ impl HyperlineClient {
         Ok(())
     }
 
+    /// Look up a customer by its `external_id`. Returns `None` if no row
+    /// matches. Used by the lazy-link path on `GET /account/billing/portal`
+    /// to recover from a prior partial link (Hyperline customer created but
+    /// the `UPDATE accounts` step never landed — race or crash). Without
+    /// this we'd orphan a customer in Hyperline and create a duplicate on
+    /// the next retry.
+    pub async fn find_customer_by_external_id(
+        &self,
+        external_id: &str,
+    ) -> Result<Option<Customer>, HyperlineError> {
+        let page: ListResponse<Customer> = self
+            .get_json(
+                "/v1/customers",
+                &[("external_id__equals", external_id), ("limit", "1")],
+            )
+            .await?;
+        Ok(page.data.into_iter().next())
+    }
+
+    /// Create a Hyperline customer. `external_id` is the local
+    /// `accounts.id` (UUID) so we can recover the mapping if our DB row
+    /// gets cleared but Hyperline's record survives. A 4xx (e.g.
+    /// duplicate `external_id`) is surfaced as `HyperlineError::Api` —
+    /// the lazy-create path checks `find_customer_by_external_id` first
+    /// so this should only fire on genuinely-new customers.
+    pub async fn create_customer(
+        &self,
+        external_id: &str,
+        name: &str,
+        email: &str,
+    ) -> Result<Customer, HyperlineError> {
+        let body = serde_json::json!({
+            "external_id": external_id,
+            "name": name,
+            "email": email,
+        });
+        self.post_json("/v1/customers", &body).await
+    }
+
     /// Fetches a wallet by its Hyperline id.
     ///
     /// Wallets are not auto-provisioned — if the customer has no wallet
