grant/keysat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Recurring subs Phase 4 — admin UI + buy-page rendering + Pro-tier gate

Browse Source 
Phase 4 surfaces the recurring-subscription schema (migration 0011) and
renewal-worker (Phase 2, commit 7007bf8) through every layer operators
and buyers actually see:

API
- Policy struct + repo gain is_recurring, renewal_period_days,
  grace_period_days, trial_days. RecurringConfig / RecurringUpdate
  helper structs keep create_policy / update_policy signatures
  manageable.
- CreatePolicyReq + UpdatePolicyReq accept all four fields. Validation
  rejects internally inconsistent combos (recurring=true with period=0,
  trial > renewal period, period >5y, grace >90d).
- New tier::enforce_recurring_feature gate. Pro/Patron only — Creator
  and Unlicensed get a 402 with upgrade_url. The gate fires on both
  create-policy and the false→true transition in update-policy.
- list_public_policies now surfaces is_recurring, renewal_period_days,
  trial_days so SDKs and the buy page can render cadence.

Admin UI (web/index.html)
- Create-policy form gets a "Recurring subscription (Pro)" section:
  is_recurring checkbox + cadence preset (monthly/quarterly/etc/custom)
  + grace period + trial days. Live enable/disable: the inputs gray
  out unless the box is ticked, and the custom-days input grays out
  unless "Custom" is selected.
- Edit-policy modal mirrors the same section, pre-populated from the
  policy's current values.
- Policies-list table shows a gold "every Nd" badge alongside the
  trial badge so operators can see at a glance which policies renew.

Buy page (/buy/<slug>)
- Tier cards on a recurring policy render a "Renews monthly/annually/
  every N days" meta line + a "/mo" / "/yr" / "/Nd" suffix on the
  price unit, so the headline reads "$25 / mo" not just "$25".
- First-cycle trial banner shows when trial_days > 0.
- TIERS JSON map exposes is_recurring + renewal_period_days +
  trial_days so the JS price-update path keeps the cadence suffix
  in sync when the buyer clicks between tiers.

Tests (+4, total now 53)
- recurring_policy_blocked_on_creator_tier — 402 + upgrade_url
- pro_tier_creates_monthly_recurring_policy — full create + verify
  via both admin GET and public list endpoint
- recurring_requires_positive_period — validator rejects period=0
- edit_policy_to_recurring_respects_tier_gate — Creator 402 on flip,
  Pro 200 on same flip, name-only PATCH on already-recurring policy
  doesn't re-fire the gate after downgrade

Drive-by: wrap the state-machine ASCII diagram in subscriptions.rs in
a ```text fence so cargo's doc-test runner stops trying to compile box
characters as Rust tokens.
This commit is contained in:
Grant
2026-05-08 17:47:55 -05:00
parent 7007bf8204
commit c301eacfaa
8 changed files with 762 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
licensing-service/src/api/buy_page.rs
+59 -2
View File
@@ -595,13 +595,27 @@ footer.kfooter a:hover {{ color:var(--navy-900); }}
}}
// Reflect new base price in the cert card. For fiat-priced
// products the unit cell ("sats" → "USD" / "EUR") also swaps.
// Recurring tiers: append a cadence suffix to the unit so the
// headline price reads "$25 / mo" not just "$25".
const t = TIERS[slug];
const fmt = formatTierPrice(t);
currentBaseFmt = fmt.amount;
priceStrike.style.display = 'none';
priceTag.style.display = 'none';
const unitEl = document.querySelector('.unit');
if (unitEl) unitEl.textContent = fmt.unit;
let unitText = fmt.unit;
if (t.is_recurring) {{
const days = t.renewal_period_days || 0;
const suffix = days === 7 ? ' / wk'
: days === 30 ? ' / mo'
: days === 90 ? ' / qtr'
: days === 180 ? ' / 6mo'
: days === 365 ? ' / yr'
: days > 0 ? (' / ' + days + 'd')
: '';
unitText = fmt.unit + suffix;
}}
if (unitEl) unitEl.textContent = unitText;
if (priceLabel) priceLabel.textContent = 'Price · ' + t.name;
// Free tier: render "FREE", swap CTA to "Redeem license" so the
// buyer never sees "Pay with Bitcoin" for a 0-amount product.
@@ -963,15 +977,55 @@ fn render_tier_picker(
} else {
String::new()
};
// Recurring-subscription cadence rendering:
// - Tier card shows "Renews every N days" / "monthly" / "annually" beneath duration.
// - The price unit gets a "/mo" / "/yr" / "/Nd" suffix so the headline price
// reads as a subscription rate, not a one-time cost.
// - First-cycle trial banner shows when trial_days > 0.
let (cadence_suffix, recurring_meta, trial_banner) = if p.is_recurring {
let days = p.renewal_period_days.max(0);
let (suffix, label) = match days {
7 => ("/wk", "Renews weekly".to_string()),
30 => ("/mo", "Renews monthly".to_string()),
90 => ("/qtr", "Renews quarterly".to_string()),
180 => ("/6mo", "Renews semi-annually".to_string()),
365 => ("/yr", "Renews annually".to_string()),
other => (
// Static lifetime suffix for non-canonical cadences
// (use Box::leak only for predictable known values;
// fall back to plain "" + custom meta text).
"",
format!("Renews every {other} days"),
),
};
let trial_banner = if p.trial_days > 0 {
format!(
"<div class=\"tier-meta\" style=\"color:var(--gold-700); font-weight:600\">{} day free trial</div>",
p.trial_days
)
} else {
String::new()
};
(
suffix,
format!("<div class=\"tier-meta\">{}</div>", html_escape(&label)),
trial_banner,
)
} else {
("", String::new(), String::new())
};
format!(
r#"<div class="{classes}" data-policy-slug="{slug}">{popular_pill}<div class="tier-name">{name}</div><div class="tier-price">{price_fmt}<span class="tier-price-unit">{price_unit}</span></div>{dur_html}{trial_meta}{description_html}{entitlements_html}<button type="button" class="tier-select-btn">Select</button></div>"#,
r#"<div class="{classes}" data-policy-slug="{slug}">{popular_pill}<div class="tier-name">{name}</div><div class="tier-price">{price_fmt}<span class="tier-price-unit">{price_unit}{cadence_suffix}</span></div>{dur_html}{recurring_meta}{trial_banner}{trial_meta}{description_html}{entitlements_html}<button type="button" class="tier-select-btn">Select</button></div>"#,
classes = classes,
slug = slug_attr,
popular_pill = popular_pill,
name = name,
price_fmt = price_fmt,
price_unit = price_unit,
cadence_suffix = cadence_suffix,
dur_html = dur_html,
recurring_meta = recurring_meta,
trial_banner = trial_banner,
trial_meta = trial_meta,
description_html = description_html,
entitlements_html = entitlements_html,
@@ -1017,6 +1071,9 @@ fn build_tiers_json(
"price_sats": price_sats_value,
"price_currency": product.price_currency,
"price_value": price_value,
"is_recurring": p.is_recurring,
"renewal_period_days": p.renewal_period_days,
"trial_days": p.trial_days,
}),
);
}
licensing-service/src/api/policies.rs
+138
View File
@@ -52,12 +52,71 @@ pub struct CreatePolicyReq {
/// Free-form label for the tip recipient (audit/UI).
#[serde(default)]
pub tip_label: Option<String>,
/// Recurring-subscription cadence (migration 0011). When `is_recurring`
/// is true, the renewal worker re-invoices every `renewal_period_days`.
/// Pro-tier feature.
#[serde(default)]
pub is_recurring: bool,
#[serde(default)]
pub renewal_period_days: i64,
/// Days the subscription stays in `past_due` before lapsing. Defaults
/// to 7 (matches migration default) when omitted on a recurring policy.
#[serde(default)]
pub grace_period_days: Option<i64>,
/// Optional free-trial length at the first cycle. 0 = no trial.
#[serde(default)]
pub trial_days: i64,
}
fn default_max_machines() -> i64 {
1
}
/// Centralised validation for the recurring-subscription knobs. Called
/// from both create + update paths so the rules stay in one place. We
/// reject internally inconsistent combos (recurring=true with period=0,
/// trial>renewal period, etc.) so the renewal worker never has to
/// defensively normalize bad rows.
fn validate_recurring(
is_recurring: bool,
renewal_period_days: i64,
grace_period_days: i64,
trial_days: i64,
) -> AppResult<()> {
if !is_recurring {
// Non-recurring policy: ignore the other knobs (they may be
// carried in legacy callers).
return Ok(());
}
if renewal_period_days <= 0 {
return Err(AppError::BadRequest(
"renewal_period_days must be > 0 when is_recurring=true".into(),
));
}
if renewal_period_days > 366 * 5 {
return Err(AppError::BadRequest(
"renewal_period_days unreasonably large (>5 years)".into(),
));
}
if grace_period_days < 0 {
return Err(AppError::BadRequest("grace_period_days must be >= 0".into()));
}
if grace_period_days > 90 {
return Err(AppError::BadRequest(
"grace_period_days capped at 90 — operators wanting longer should disable lapsing manually".into(),
));
}
if trial_days < 0 {
return Err(AppError::BadRequest("trial_days must be >= 0".into()));
}
if trial_days > renewal_period_days {
return Err(AppError::BadRequest(format!(
"trial_days ({trial_days}) cannot exceed renewal_period_days ({renewal_period_days})"
)));
}
Ok(())
}
pub async fn create(
State(state): State<AppState>,
headers: HeaderMap,
@@ -104,6 +163,28 @@ pub async fn create(
));
}
let tip_label = req.tip_label.as_deref().filter(|s| !s.trim().is_empty());
// Recurring config: fall back to migration default (7 days grace) when
// operator omits the field. Validation rejects inconsistent combos.
let grace_period_days = req.grace_period_days.unwrap_or(7);
validate_recurring(
req.is_recurring,
req.renewal_period_days,
grace_period_days,
req.trial_days,
)?;
// Pro-tier gate: only Pro/Patron can create recurring policies. Free
// and Creator tiers see a 402 with an upgrade URL.
if req.is_recurring {
crate::api::tier::enforce_recurring_feature(&state).await?;
}
let recurring = repo::RecurringConfig {
is_recurring: req.is_recurring,
renewal_period_days: req.renewal_period_days,
grace_period_days,
trial_days: req.trial_days,
};
let policy = repo::create_policy(
&state.db,
&product.id,
@@ -119,6 +200,7 @@ pub async fn create(
tip_recipient,
req.tip_pct_bps,
tip_label,
recurring,
)
.await?;
let _ = repo::insert_audit(
@@ -341,6 +423,17 @@ pub struct UpdatePolicyReq {
pub entitlements: Option<Vec<String>>,
#[serde(default)]
pub metadata: Option<serde_json::Value>,
/// Recurring-subscription knobs. Each is optional (`None` = "leave
/// untouched"). Validation rejects internally inconsistent combos
/// (e.g. flipping is_recurring=true while leaving renewal_period_days=0).
#[serde(default)]
pub is_recurring: Option<bool>,
#[serde(default)]
pub renewal_period_days: Option<i64>,
#[serde(default)]
pub grace_period_days: Option<i64>,
#[serde(default)]
pub trial_days: Option<i64>,
}
fn deser_double_option_i64<'de, D>(de: D) -> Result<Option<Option<i64>>, D::Error>
@@ -375,6 +468,41 @@ pub async fn update(
}
}
// Validate recurring-subscription knobs *if* any are being touched. We
// need to load the current row to fill in untouched fields so the
// validator sees the post-update shape.
if req.is_recurring.is_some()
|| req.renewal_period_days.is_some()
|| req.grace_period_days.is_some()
|| req.trial_days.is_some()
{
let current = repo::get_policy_by_id(&state.db, &id)
.await?
.ok_or_else(|| AppError::NotFound(format!("policy '{id}'")))?;
let next_is_recurring = req.is_recurring.unwrap_or(current.is_recurring);
let next_renewal = req
.renewal_period_days
.unwrap_or(current.renewal_period_days);
let next_grace = req.grace_period_days.unwrap_or(current.grace_period_days);
let next_trial = req.trial_days.unwrap_or(current.trial_days);
validate_recurring(next_is_recurring, next_renewal, next_grace, next_trial)?;
// Pro-tier gate: refuse to flip a policy to recurring on a
// tier without `recurring_billing`. We only check on a positive
// transition (false → true) — patches that leave is_recurring
// alone or turn it OFF are fine for everyone.
let was_recurring = current.is_recurring;
if !was_recurring && next_is_recurring {
crate::api::tier::enforce_recurring_feature(&state).await?;
}
}
let recurring_update = repo::RecurringUpdate {
is_recurring: req.is_recurring,
renewal_period_days: req.renewal_period_days,
grace_period_days: req.grace_period_days,
trial_days: req.trial_days,
};
let updated = repo::update_policy(
&state.db,
&id,
@@ -386,6 +514,7 @@ pub async fn update(
req.price_sats_override,
req.entitlements.as_deref(),
req.metadata.as_ref(),
recurring_update,
)
.await?;
let _ = repo::insert_audit(
@@ -403,6 +532,10 @@ pub async fn update(
"max_machines": req.max_machines,
"price_sats_override": req.price_sats_override,
"entitlements": req.entitlements,
"is_recurring": req.is_recurring,
"renewal_period_days": req.renewal_period_days,
"grace_period_days": req.grace_period_days,
"trial_days": req.trial_days,
}),
)
.await;
@@ -492,6 +625,11 @@ pub async fn list_public_policies(
"is_trial": p.is_trial,
"entitlements": p.entitlements,
"highlighted": highlighted,
// Recurring-subscription cadence — buy page renders
// "Renews every N days" / "$X/month" when is_recurring=true.
"is_recurring": p.is_recurring,
"renewal_period_days": p.renewal_period_days,
"trial_days": p.trial_days,
})
})
.collect();
licensing-service/src/api/tier.rs
+20
View File
@@ -212,6 +212,26 @@ pub async fn enforce_policy_cap(state: &AppState, product_id: &str) -> AppResult
Ok(())
}
/// Refuse to mark a policy as recurring unless the operator's self-tier
/// carries the `recurring_billing` entitlement. Pro and Patron tiers
/// have it; Creator does not. Called from both create-policy and
/// update-policy paths so operators can't sneak past by patching a
/// non-recurring policy to recurring after creation.
pub async fn enforce_recurring_feature(state: &AppState) -> AppResult<()> {
let tier = current(state).await;
if tier.has("recurring_billing") {
return Ok(());
}
Err(AppError::PaymentRequired {
message: format!(
"Recurring subscriptions require Pro or Patron. You're on {}. \
Upgrade to enable monthly/annual billing.",
tier.display_name
),
upgrade_url: UPGRADE_URL_PRO.to_string(),
})
}
/// Refuse a new discount code if the operator is at the Creator-tier
/// active-codes cap and lacks `unlimited_codes`. Counts only ACTIVE
/// codes — operators can disable old codes to free up slots, which is
licensing-service/src/db/repo.rs
+80 -2
View File
@@ -763,8 +763,33 @@ const POLICY_COLS: &str = "id, product_id, name, slug, duration_seconds, grace_s
tip_recipient, tip_pct_bps, tip_label,
max_machines, is_trial, price_sats_override,
entitlements_json, metadata_json, active, public,
is_recurring, renewal_period_days, grace_period_days, trial_days,
created_at, updated_at";
/// Bundles the recurring-subscription knobs so we don't keep growing
/// `create_policy`'s positional argument list. Pass `RecurringConfig::off()`
/// for one-off policies. Validation (positive renewal period, sane trial
/// length) lives in the API layer; the repo just persists.
#[derive(Debug, Clone, Copy, Default)]
pub struct RecurringConfig {
pub is_recurring: bool,
pub renewal_period_days: i64,
/// Defaults to 7 days when omitted (matches migration 0011 default).
pub grace_period_days: i64,
pub trial_days: i64,
}
impl RecurringConfig {
pub fn off() -> Self {
Self {
is_recurring: false,
renewal_period_days: 0,
grace_period_days: 7,
trial_days: 0,
}
}
}
#[allow(clippy::too_many_arguments)]
pub async fn create_policy(
pool: &SqlitePool,
@@ -781,6 +806,7 @@ pub async fn create_policy(
tip_recipient: Option<&str>,
tip_pct_bps: i64,
tip_label: Option<&str>,
recurring: RecurringConfig,
) -> AppResult<Policy> {
let id = Uuid::new_v4().to_string();
let now = Utc::now().to_rfc3339();
@@ -792,8 +818,10 @@ pub async fn create_policy(
"INSERT INTO policies
(id, product_id, name, slug, duration_seconds, grace_seconds, max_machines,
is_trial, price_sats_override, entitlements_json, metadata_json, active, public,
tip_recipient, tip_pct_bps, tip_label, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 1, ?, ?, ?, ?, ?)",
tip_recipient, tip_pct_bps, tip_label,
is_recurring, renewal_period_days, grace_period_days, trial_days,
created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
)
.bind(&id)
.bind(product_id)
@@ -809,6 +837,10 @@ pub async fn create_policy(
.bind(tip_recipient)
.bind(tip_pct)
.bind(tip_label)
.bind(recurring.is_recurring as i64)
.bind(recurring.renewal_period_days)
.bind(recurring.grace_period_days)
.bind(recurring.trial_days)
.bind(&now)
.bind(&now)
.execute(pool)
@@ -882,6 +914,17 @@ pub async fn list_public_policies_by_product(
/// have hard-coded into integration docs or buy URLs. Tip-related fields
/// have their own admin endpoint (`set_policy_tip_config`) since they
/// have their own validation rules (basis points, paired recipient/pct).
/// Patch-style updates for the recurring-subscription knobs. Each field is
/// `Option<…>` — `None` means "leave alone", `Some(v)` means "set". Bundled
/// to keep `update_policy`'s signature manageable.
#[derive(Debug, Default, Clone, Copy)]
pub struct RecurringUpdate {
pub is_recurring: Option<bool>,
pub renewal_period_days: Option<i64>,
pub grace_period_days: Option<i64>,
pub trial_days: Option<i64>,
}
#[allow(clippy::too_many_arguments)]
pub async fn update_policy(
pool: &SqlitePool,
@@ -894,6 +937,7 @@ pub async fn update_policy(
price_sats_override: Option<Option<i64>>,
entitlements: Option<&[String]>,
metadata: Option<&serde_json::Value>,
recurring: RecurringUpdate,
) -> AppResult<Policy> {
let mut sets: Vec<&str> = Vec::new();
if name.is_some() {
@@ -920,6 +964,18 @@ pub async fn update_policy(
if metadata.is_some() {
sets.push("metadata_json = ?");
}
if recurring.is_recurring.is_some() {
sets.push("is_recurring = ?");
}
if recurring.renewal_period_days.is_some() {
sets.push("renewal_period_days = ?");
}
if recurring.grace_period_days.is_some() {
sets.push("grace_period_days = ?");
}
if recurring.trial_days.is_some() {
sets.push("trial_days = ?");
}
if sets.is_empty() {
return get_policy_by_id(pool, id)
.await?
@@ -957,6 +1013,18 @@ pub async fn update_policy(
meta_json = serde_json::to_string(m).unwrap_or_else(|_| "{}".into());
q = q.bind(&meta_json);
}
if let Some(v) = recurring.is_recurring {
q = q.bind(v as i64);
}
if let Some(v) = recurring.renewal_period_days {
q = q.bind(v);
}
if let Some(v) = recurring.grace_period_days {
q = q.bind(v);
}
if let Some(v) = recurring.trial_days {
q = q.bind(v);
}
q = q.bind(&now).bind(id);
let rows = q.execute(pool).await?.rows_affected();
if rows == 0 {
@@ -1006,6 +1074,12 @@ fn row_to_policy(row: sqlx::sqlite::SqliteRow) -> Policy {
let active_int: i64 = row.get("active");
let is_trial_int: i64 = row.get("is_trial");
let public_int: i64 = row.try_get("public").unwrap_or(1);
// Recurring fields land in migration 0011 — fall back to defaults so
// older databases (pre-0011, theoretically possible) don't crash here.
let is_recurring_int: i64 = row.try_get("is_recurring").unwrap_or(0);
let renewal_period_days: i64 = row.try_get("renewal_period_days").unwrap_or(0);
let grace_period_days: i64 = row.try_get("grace_period_days").unwrap_or(7);
let trial_days: i64 = row.try_get("trial_days").unwrap_or(0);
Policy {
id: row.get("id"),
product_id: row.get("product_id"),
@@ -1023,6 +1097,10 @@ fn row_to_policy(row: sqlx::sqlite::SqliteRow) -> Policy {
tip_recipient: row.get("tip_recipient"),
tip_pct_bps: row.get("tip_pct_bps"),
tip_label: row.get("tip_label"),
is_recurring: is_recurring_int != 0,
renewal_period_days,
grace_period_days,
trial_days,
created_at: row.get("created_at"),
updated_at: row.get("updated_at"),
}
licensing-service/src/models.rs
+22
View File
@@ -166,10 +166,32 @@ pub struct Policy {
/// Defaults to true; migration 0007 adds this column.
#[serde(default = "default_true")]
pub public: bool,
/// Recurring subscription cadence (migration 0011). When `is_recurring`
/// is true, the renewal worker will create a fresh invoice every
/// `renewal_period_days` and the buy page renders the price as
/// "every N days" / "monthly".
#[serde(default)]
pub is_recurring: bool,
/// Days between renewal cycles. Ignored when `is_recurring = false`.
/// Common values: 30 (monthly), 365 (annual).
#[serde(default)]
pub renewal_period_days: i64,
/// Days the subscription stays in `past_due` before transitioning to
/// `lapsed`. Migration default is 7.
#[serde(default = "default_grace_period_days")]
pub grace_period_days: i64,
/// Free-trial length at first cycle. 0 = no trial. The first invoice
/// is still issued (for $0 / 1-sat) so the buyer email + license
/// flow is consistent; renewal worker charges the real price after
/// `trial_days`.
#[serde(default)]
pub trial_days: i64,
pub created_at: String,
pub updated_at: String,
}
fn default_grace_period_days() -> i64 { 7 }
fn default_true() -> bool { true }
/// A machine activated under a license. One row per active install.
licensing-service/src/subscriptions.rs
+2
View File
@@ -16,6 +16,7 @@
//!
//! State machine recap (full diagram in the design doc):
//!
//! ```text
//! ┌─────────┐ cycle ends ┌──────────┐
//! │ active │ ────────────▶ │ past_due │
//! └─────────┘ └──────────┘
@@ -26,6 +27,7 @@
//! ┌────────┐
//! │ lapsed │
//! └────────┘
//! ```
//!
//! Cancellation can flip from `active` or `past_due` → `cancelled`
//! at any point (admin or buyer-initiated). Cancelled subs stop