docs: document delinquent relay status across spec

Co-authored-by: userAdityaa <aditya.chaudhary1558@gmail.com>
Co-committed-by: userAdityaa <aditya.chaudhary1558@gmail.com>

backend/README.md

@@ -70,9 +70,9 @@ Public exceptions:
 - `GET /plans/:id`
 - `POST /stripe/webhook` (validated with Stripe signatures)
 
-- `GET /identity` — get auth identity (`pubkey`, `is_admin`)
+- `GET /identity` — get auth identity (`pubkey`, `is_admin`); side-effect-free
 - `GET /tenants` — list tenants (admin)
-- `POST /tenants` — create current auth pubkey as tenant
+- `POST /tenants` — idempotently ensure a tenant row exists for the current auth pubkey (creates Stripe customer + tenant on first call, returns existing tenant otherwise)
 - `GET /tenants/:pubkey` — get tenant (admin or same tenant)
 - `PUT /tenants/:pubkey/billing` — update tenant `nwc_url` (admin or same tenant)
 - `GET /relays` — list relays (`?tenant=<pubkey>` allowed for admin only)

backend/spec/api.md

@@ -46,9 +46,8 @@ Notes:
 
 - Serves `GET /identity`
 - Authorizes anyone, but must be authorized
-- If a tenant for the identity doesn't exist:
-  - Call the Stripe API to create a new customer
-  - Create a new tenant using `command.create_tenant` with payload and `stripe_customer_id`. No subscription is created yet — that happens when the first relay is added.
+- Side-effect-free: returns `{ pubkey, is_admin }` only
+- Clients must call `POST /tenants` before any tenant-scoped write
 - Return `data` is an `Identity` struct
 
 --- Tenant routes
@@ -59,6 +58,18 @@ Notes:
 - Authorizes admin only
 - Return `data` is a list of tenant structs from `query.list_tenants`
 
+## `async fn create_tenant(...) -> Response`
+
+- Serves `POST /tenants`
+- Authorizes anyone, but must be authorized
+- No request body; target pubkey is derived from NIP-98 auth
+- Idempotent: if a tenant already exists for the auth pubkey, return it without calling Stripe or writing to the DB
+- Otherwise, call the Stripe API to create a new customer and create a new tenant using `command.create_tenant` with the resulting `stripe_customer_id`. No subscription is created yet — that happens when the first relay is added.
+- On unique-constraint race (`pubkey-exists`), re-fetch and return the existing tenant
+- If Stripe customer creation fails, return `code=stripe-customer-create-failed`
+- Always returns `200` (create-or-get is uniform)
+- Return `data` is a single `Tenant` struct
+
 ## `async fn get_tenant(...) -> Response`
 
 - Serves `GET /tenants/:pubkey`
@@ -121,7 +132,7 @@ Notes:
 
 - Serves `POST /relays/:id/deactivate`
 - Authorizes admin or relay owner
-- If relay is already inactive, return a `400` with `code=relay-is-inactive`
+- If relay status is `inactive` or `delinquent`, return a `400` with `code=relay-is-inactive`
 - Call `command.deactivate_relay`
 - Return `data` is empty
 

backend/spec/billing.md

@@ -28,7 +28,7 @@ Manages the Stripe subscription and subscription items for a relay's tenant. Onl
 
 - Fetch the relay and tenant associated with the `activity`
 - **If relay plan is `free`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then check cleanup (below). Return early.
-- **If relay is `inactive`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then check cleanup (below). Return early.
+- **If relay is `inactive` or `delinquent`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then check cleanup (below). Return early.
 - **If relay is `active` and on a paid plan**:
   - **Ensure subscription exists**: If the tenant has no `stripe_subscription_id`, create a Stripe subscription for the customer with `collection_method: "charge_automatically"` and the relay's price as the first item. Save the subscription ID via `command.set_tenant_subscription` and the item ID via `command.set_relay_subscription_item`. Return early.
   - **Sync the subscription item**: If the tenant already has a subscription, create or update the relay's Stripe subscription item to the plan's `stripe_price_id` via the Stripe API, then call `command.set_relay_subscription_item`.
@@ -85,7 +85,7 @@ Skip invoices with `amount_due` of 0.
 - Look up tenant by `stripe_customer_id`
 - If tenant has `past_due_at` set:
   - Clear `past_due_at` via `command.clear_tenant_past_due`
-  - Find all `inactive` relays for the tenant that were deactivated due to non-payment (i.e. relays on paid plans that are inactive)
+  - Find all `delinquent` relays on paid plans for the tenant (relays marked delinquent by the billing system due to non-payment)
   - Reactivate each one via `command.activate_relay`
 
 ## `fn handle_invoice_payment_failed(&self, invoice: &Invoice)`
@@ -98,7 +98,7 @@ Skip invoices with `amount_due` of 0.
 ## `fn handle_invoice_overdue(&self, invoice: &Invoice)`
 
 - Look up tenant by `stripe_customer_id`
-- Deactivate all active relays on paid plans via `command.deactivate_relay`
+- Mark all active relays on paid plans as delinquent via `command.mark_relay_delinquent` (sets status to `delinquent`, distinct from user-initiated `deactivate_relay`)
 - Send a DM via `robot.send_dm` notifying the tenant that their paid relays have been deactivated due to non-payment
 
 ## `fn handle_subscription_updated(&self, subscription: &Subscription)`
@@ -106,7 +106,7 @@ Skip invoices with `amount_due` of 0.
 - Look up tenant by `stripe_customer_id`
 - If subscription status is `canceled` or `unpaid`:
   - Clear `stripe_subscription_id` via `command.clear_tenant_subscription`
-  - Deactivate all active paid relays for the tenant via `command.deactivate_relay`
+  - Mark all active paid relays as delinquent via `command.mark_relay_delinquent`
 
 ## `fn handle_subscription_deleted(&self, subscription: &Subscription)`
 

backend/spec/command.md

@@ -44,6 +44,14 @@ Notes:
 
 - Sets relay status to `inactive`
 - Logs activity as `(deactivate_relay, relay_id)`
+- Used for user/admin-initiated deactivation only
+
+## `pub fn mark_relay_delinquent(&self, relay: &Relay) -> Result<()>`
+
+- Sets relay status to `delinquent`
+- Logs activity as `(deactivate_relay, relay_id)`
+- Used exclusively by the billing system when a relay's subscription becomes past due
+- `delinquent` relays are automatically reactivated via `activate_relay` when payment is received
 
 ## `pub fn activate_relay(&self, relay: &Relay) -> Result<()>`
 

backend/spec/models.md

@@ -69,7 +69,7 @@ A relay is a nostr relay owned by a `tenant` and hosted by the attached zooid in
 - `subdomain` - the relay's subdomain
 - `plan` - the relay's plan
 - `stripe_subscription_item_id` (nullable) - the Stripe subscription item id. Only set for relays on paid plans.
-- `status` - `active|inactive`. Only `active` relays count toward billing.
+- `status` - one of `active|inactive|delinquent`. Only `active` relays count toward billing. `delinquent` is set by the billing system when a relay's subscription becomes past due; `inactive` is set when a user or admin manually deactivates a relay.
 - `synced` - whether the relay has been successfully synced to zooid at least once.
 - `sync_error` - a string indicating any errors encountered when synchronizing.
 - `info_name` - the relay's name

backend/src/api.rs

@@ -143,7 +143,7 @@ impl Api {
             .route("/identity", get(get_identity))
             .route("/plans", get(list_plans))
             .route("/plans/:id", get(get_plan))
-            .route("/tenants", get(list_tenants))
+            .route("/tenants", get(list_tenants).post(create_tenant))
             .route("/tenants/:pubkey", get(get_tenant).put(update_tenant))
             .route("/tenants/:pubkey/relays", get(list_tenant_relays))
             .route("/relays", get(list_relays).post(create_relay))
@@ -401,10 +401,17 @@ async fn get_identity(
 ) -> std::result::Result<Response, ApiError> {
     let pubkey = state.api.extract_auth_pubkey(&headers)?;
     let is_admin = state.api.admins.iter().any(|a| a == &pubkey);
+    Ok(ok(StatusCode::OK, IdentityResponse { pubkey, is_admin }))
+}
+
+async fn create_tenant(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+) -> std::result::Result<Response, ApiError> {
+    let pubkey = state.api.extract_auth_pubkey(&headers)?;
 
-    // Ensure tenant exists.
     match state.api.query.get_tenant(&pubkey).await {
-        Ok(Some(_)) => {}
+        Ok(Some(t)) => Ok(ok(StatusCode::OK, t)),
         Ok(None) => {
             let stripe_customer_id = match state.api.billing.stripe_create_customer(&pubkey).await {
                 Ok(id) => id,
@@ -428,27 +435,35 @@ async fn get_identity(
             };
 
             match state.api.command.create_tenant(&tenant).await {
-                Ok(()) => {}
-                Err(e) if matches!(map_unique_error(&e), Some("pubkey-exists")) => {}
-                Err(e) => {
-                    return Ok(err(
-                        StatusCode::INTERNAL_SERVER_ERROR,
-                        "internal",
-                        &e.to_string(),
-                    ));
+                Ok(()) => Ok(ok(StatusCode::OK, tenant)),
+                Err(e) if matches!(map_unique_error(&e), Some("pubkey-exists")) => {
+                    match state.api.query.get_tenant(&pubkey).await {
+                        Ok(Some(t)) => Ok(ok(StatusCode::OK, t)),
+                        Ok(None) => Ok(err(
+                            StatusCode::INTERNAL_SERVER_ERROR,
+                            "internal",
+                            "tenant row missing after unique-constraint race",
+                        )),
+                        Err(e) => Ok(err(
+                            StatusCode::INTERNAL_SERVER_ERROR,
+                            "internal",
+                            &e.to_string(),
+                        )),
+                    }
                 }
-            };
-        }
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
+                Err(e) => Ok(err(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "internal",
+                    &e.to_string(),
+                )),
+            }
         }
+        Err(e) => Ok(err(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "internal",
+            &e.to_string(),
+        )),
     }
-
-    Ok(ok(StatusCode::OK, IdentityResponse { pubkey, is_admin }))
 }
 
 async fn get_plan(Path(id): Path<String>) -> Response {

frontend/src/components/RelayDetailCard.tsx

@@ -203,6 +203,13 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
         </Show>
       </div>
 
+      <Show when={r().sync_error}>
+        <div class="rounded-lg border border-red-200 bg-red-50 px-4 py-3">
+          <p class="text-sm font-semibold text-red-800">Provisioning error</p>
+          <p class="mt-1 text-sm text-red-700 font-mono break-all">{r().sync_error}</p>
+        </div>
+      </Show>
+
       <hr class="border-gray-200" />
 
       <DetailSection title="Policy">

frontend/src/components/RelayListItem.tsx

@@ -1,4 +1,5 @@
 import { A } from "@solidjs/router"
+import { Show } from "solid-js"
 import type { Relay } from "@/lib/api"
 
 type RelayListItemProps = {
@@ -19,7 +20,17 @@ export default function RelayListItem(props: RelayListItemProps) {
               <p class="text-xs text-gray-500 break-all mt-1">Tenant: {props.relay.tenant}</p>
             )}
           </div>
-          <p class="text-xs uppercase tracking-wide text-gray-500">{props.relay.status}</p>
+          <Show
+            when={props.relay.sync_error}
+            fallback={<p class="text-xs uppercase tracking-wide text-gray-500">{props.relay.status}</p>}
+          >
+            <span
+              class="inline-flex items-center rounded-full border border-red-200 bg-red-50 px-2.5 py-0.5 text-xs font-medium text-red-700 max-w-56 truncate"
+              title={props.relay.sync_error}
+            >
+              {props.relay.sync_error}
+            </span>
+          </Show>
         </div>
       </A>
     </li>

frontend/src/lib/api.ts

@@ -205,6 +205,10 @@ export function getIdentity() {
   return callApi<undefined, Identity>("GET", "/identity")
 }
 
+export function createTenant() {
+  return callApi<undefined, Tenant>("POST", "/tenants")
+}
+
 export function getPlan(id: string) {
   return callApi<undefined, Plan>("GET", `/plans/${id}`)
 }

frontend/src/views/Login.tsx

@@ -5,6 +5,7 @@ import { PasswordSigner } from "applesauce-signers"
 import QrScanner from "qr-scanner"
 import QRCode from "qrcode"
 import { accountManager, identity, PLATFORM_NAME } from "@/lib/state"
+import { createTenant } from "@/lib/api"
 import useMinLoading from "@/components/useMinLoading"
 
 const NIP46_RELAYS = ['wss://bucket.coracle.social', 'wss://ephemeral.snowflare.cc']
@@ -69,6 +70,12 @@ export default function Login(props: LoginPageProps = {}) {
   async function completeLogin(account: ExtensionAccount | NostrConnectAccount | PrivateKeyAccount | PasswordAccount) {
     accountManager.addAccount(account)
     accountManager.setActive(account)
+    try {
+      await createTenant()
+    } catch (e) {
+      accountManager.removeAccount(account)
+      throw e
+    }
     await props.onAuthenticated?.()
   }