grant/keysat-plans

Fork 0

Files

T

Keysat 3aacbbe278 Initial commit — multi-provider + SMTP plans

2026-05-20 12:51:31 -05:00

27 KiB

Raw Blame History

Keysat multi-merchant-profile + multi-provider model

Context

Today both btcpay_config and zaprite_config are singleton rows (id INTEGER PRIMARY KEY CHECK (id = 1)), and SETTING_ACTIVE_PROVIDER picks one of the two as the daemon's process-wide active provider. Every call to state.payment_provider() returns that one provider, regardless of which product is being sold. There's no concept of a "merchant" or "seller" identity anywhere — every product on a Keysat instance is implicitly being sold by the same legal entity, through the same payment account, with the same branding and the same post-purchase landing page.

That model breaks the moment a software author wants to run ONE Keysat instance for multiple distinct businesses. Concrete example: one operator sells Recaps licenses (settled to a Recaps Zaprite org, branded as Recaps, buyers redirected to recaps.cc) AND Keysat licenses (settled to a Keysat Zaprite org, branded as Keysat, buyers redirected to keysat.xyz). Today's architecture forces both to share one merchant identity, one provider account, one branding set, one redirect URL.

This plan introduces a merchant profile layer that owns business identity, branding, redirect, optional SMTP, AND a set of payment providers. Products attach to a merchant profile (not directly to a provider). The buyer sees the merchant profile's brand at checkout and picks a payment rail from the providers attached to that profile.

Tier-gating: Creator (free) gets 1 merchant profile. Pro/Patron get N.

Why this shape, not the simpler "per-product provider override"

An earlier draft of this plan had products carry a nullable payment_provider_id override directly. That worked but conflated two concerns: business identity (who's selling this? what's the brand? where do buyers land?) and payment routing (which Stripe / Bitcoin account receives the money?). In practice an operator running two businesses wants every product of business A to share a brand AND a set of payment accounts AND a redirect; copying those fields onto every product of that business would be redundant and error-prone.

Merchant profile cleanly separates the two:

Profile = the business identity (brand, redirect, support contact, optional SMTP), and the set of payment providers that legally settle TO that business.
Provider = the technical credential to a specific payment account (BTCPay store + API key, OR Zaprite org + API key). One provider per account; a profile can have many providers (e.g. BTCPay for Bitcoin AND Zaprite for card).
Product = what's being sold, attached to one profile.

This also makes buyer-currency routing (previously a deferred future- consideration) fall out for free: the buy page shows which payment rails the product's profile supports, the buyer picks Bitcoin / Lightning / Card, we route through the right provider.

Design overview

Data model

merchant_profiles (1) ──────< (N) payment_providers
                  (1) ──────< (N) products
                  (1) ──────< (N) subscriptions  [snapshot on create]

Exactly one merchant_profiles.is_default = 1 row. Auto-created on first boot after upgrade, populated from existing SETTING_OPERATOR_NAME. New operators get one default profile too.
Each payment_provider belongs to exactly ONE profile (merchant_profile_id NOT NULL). Providers move with the business.
Each product has merchant_profile_id NOT NULL. Default to the default profile.
Each subscription snapshots BOTH merchant_profile_id and payment_provider_id at creation, so mid-cycle changes to the product don't silently redirect existing subs to a different business or rail.

Buy-page resolution at runtime

Buyer hits /buy/<slug>.
Server loads product → product's merchant profile → profile's attached providers.
Buy page renders the merchant profile's brand (name, color, support link), the product's price/tiers, and a payment-method picker exposing every rail the attached providers offer (Lightning, on-chain, card, etc.).
Buyer picks a rail. The picker resolves to one provider (e.g., "Card" → the Zaprite provider attached to this profile).
Server calls state.payment_provider_for(profile_id, rail) → create_invoice on that provider.
After settle, redirect goes to profile's post_purchase_redirect_url if set, else Keysat's default /thank-you?invoice_id=… page.

Subscription renewal resolution

Renewal worker reads sub.payment_provider_id and sub.merchant_profile_id from the subscription snapshot — never re- resolves from the product. This protects existing buyers from operator edits.

Tier gating

Creator (free) — exactly 1 merchant profile. Auto-created on first boot; can be edited but not deleted, and the create-profile endpoint refuses with 402 + upgrade URL if a Creator already has one.
Pro / Patron — unlimited merchant profiles. Same cap-resolution pattern as the existing unlimited_products / unlimited_policies entitlements (tier::current() returns the cap; admin endpoint checks before insert; the existing tier-cap modal shows the upgrade CTA).

New entitlement string: unlimited_merchant_profiles. Master Keysat's Pro and Patron policies need this added to their entitlement lists; the master operator's self-license then signs with it baked in.

Schema (migration 0020)

PRAGMA foreign_keys = ON;

CREATE TABLE merchant_profiles (
    id                          TEXT PRIMARY KEY,           -- UUID v4
    name                        TEXT NOT NULL,              -- "Recaps", "Keysat"
    legal_name                  TEXT,                       -- optional, for receipts/tax
    support_url                 TEXT,
    support_email               TEXT,
    brand_color                 TEXT,                       -- hex
    post_purchase_redirect_url  TEXT,                       -- NULL = Keysat default /thank-you
    is_default                  INTEGER NOT NULL DEFAULT 0,
    -- Optional per-profile SMTP override. NULL means inherit the
    -- StartOS-level / Keysat-singleton SMTP config. Lets a Pro/Patron
    -- operator running 3 businesses send emails from 3 different
    -- domains/senders WITHOUT having to configure 3 separate StartOS
    -- accounts. Pairs with the keysat-smtp-emails plan.
    smtp_host                   TEXT,
    smtp_port                   INTEGER,
    smtp_username               TEXT,
    smtp_password               TEXT,                       -- encrypted at rest (TBD)
    smtp_from_address           TEXT,
    smtp_from_name              TEXT,
    smtp_use_starttls           INTEGER NOT NULL DEFAULT 1,
    created_at                  TEXT NOT NULL,
    updated_at                  TEXT NOT NULL,
    CHECK (is_default IN (0, 1)),
    CHECK (smtp_use_starttls IN (0, 1))
);
CREATE UNIQUE INDEX idx_merchant_profiles_one_default
    ON merchant_profiles(is_default) WHERE is_default = 1;

CREATE TABLE payment_providers (
    id                  TEXT PRIMARY KEY,                   -- UUID v4
    merchant_profile_id TEXT NOT NULL REFERENCES merchant_profiles(id),
    kind                TEXT NOT NULL,                      -- 'btcpay' | 'zaprite'
    label               TEXT NOT NULL,                      -- "Recaps BTCPay", operator-set
    api_key             TEXT NOT NULL,
    base_url            TEXT NOT NULL,
    webhook_id          TEXT,
    webhook_secret      TEXT,                               -- BTCPay HMAC; NULL for Zaprite
    store_id            TEXT,                               -- BTCPay only
    connected_at        TEXT NOT NULL,
    updated_at          TEXT NOT NULL,
    CHECK (kind IN ('btcpay', 'zaprite'))
);
CREATE INDEX idx_payment_providers_profile ON payment_providers(merchant_profile_id);
-- Within a profile, at most one provider of each kind (avoid the
-- two-BTCPay-providers-same-business confusion):
CREATE UNIQUE INDEX idx_payment_providers_profile_kind
    ON payment_providers(merchant_profile_id, kind);

ALTER TABLE products
    ADD COLUMN merchant_profile_id TEXT
    REFERENCES merchant_profiles(id);
CREATE INDEX idx_products_profile ON products(merchant_profile_id);

ALTER TABLE subscriptions
    ADD COLUMN merchant_profile_id TEXT REFERENCES merchant_profiles(id),
    ADD COLUMN payment_provider_id TEXT REFERENCES payment_providers(id);
CREATE INDEX idx_subs_profile  ON subscriptions(merchant_profile_id);
CREATE INDEX idx_subs_provider ON subscriptions(payment_provider_id);

Migration body (data port)

-- 1. Create the default merchant profile from existing operator settings.
INSERT INTO merchant_profiles(
    id, name, support_url, support_email, brand_color,
    post_purchase_redirect_url, is_default, created_at, updated_at
)
SELECT lower(hex(randomblob(16))),
       COALESCE((SELECT value FROM settings WHERE key='operator_name'), 'Keysat'),
       NULL, NULL, NULL, NULL,
       1, datetime('now'), datetime('now');

-- 2. Migrate btcpay_config → payment_providers (if present), attached to default.
INSERT INTO payment_providers(
    id, merchant_profile_id, kind, label,
    api_key, base_url, webhook_id, webhook_secret, store_id,
    connected_at, updated_at
)
SELECT lower(hex(randomblob(16))),
       (SELECT id FROM merchant_profiles WHERE is_default = 1),
       'btcpay', 'BTCPay (migrated)',
       api_key, base_url, webhook_id, webhook_secret, store_id,
       connected_at, connected_at
FROM btcpay_config;

-- 3. Same for zaprite_config.
INSERT INTO payment_providers(
    id, merchant_profile_id, kind, label,
    api_key, base_url, webhook_id, webhook_secret, store_id,
    connected_at, updated_at
)
SELECT lower(hex(randomblob(16))),
       (SELECT id FROM merchant_profiles WHERE is_default = 1),
       'zaprite', 'Zaprite (migrated)',
       api_key, base_url, webhook_id, NULL, NULL,
       connected_at, connected_at
FROM zaprite_config;

-- 4. Drop the old singleton tables.
DROP TABLE btcpay_config;
DROP TABLE zaprite_config;
DELETE FROM settings WHERE key = 'active_payment_provider';

-- 5. Backfill products + subscriptions to point at the migrated default.
UPDATE products
   SET merchant_profile_id = (SELECT id FROM merchant_profiles WHERE is_default = 1);
UPDATE subscriptions
   SET merchant_profile_id = (SELECT id FROM merchant_profiles WHERE is_default = 1),
       payment_provider_id = (
           SELECT id FROM payment_providers
           WHERE merchant_profile_id = (SELECT id FROM merchant_profiles WHERE is_default = 1)
             AND kind = (
                 -- Resolve the original provider for back-compat. Use whichever
                 -- provider the active-provider setting pointed at; fall back to
                 -- BTCPay if both exist (preserves existing single-provider
                 -- operator behavior).
                 CASE
                     WHEN EXISTS (SELECT 1 FROM payment_providers
                                  WHERE merchant_profile_id =
                                        (SELECT id FROM merchant_profiles WHERE is_default = 1)
                                    AND kind = 'btcpay')
                     THEN 'btcpay'
                     ELSE 'zaprite'
                 END
             )
       );

Additive-then-cutover; not reversible without a backup restore. Release notes call this out as a one-way migration (consistent with the v0.2.0:1+ migration framing). Existing single-provider operators see no behavior change — their setup becomes "1 profile + 1 provider," products and subs all attach to that profile.

Rust changes

src/merchant_profiles.rs (new):

pub struct MerchantProfile mirroring a row.
pub async fn list(pool) -> Vec<MerchantProfile>, get_by_id, get_default, create, update, delete.
Tier gate inside create — refuses with AppError::TierCap (existing type that triggers the 402 + upgrade modal) when Creator already has one profile.

src/payment/mod.rs:

pub struct PaymentProviderConfig mirroring a row (now includes merchant_profile_id).
pub fn build_provider(cfg: &PaymentProviderConfig) -> Arc<dyn PaymentProvider> factory dispatching on kind.
repo::list_providers_for_profile(pool, profile_id), repo::get_provider_by_id, etc.
Drop SETTING_ACTIVE_PROVIDER constant + read/write_active_provider_preference.
Add a "rail" concept: each provider impl declares which payment rails it offers (enum Rail { Lightning, OnChain, Card, … }). The buy page uses this to render the payment-method picker.

src/api/mod.rs (AppState):

Replace single payment_provider accessor with two:
- state.merchant_profile_for(product_id) -> MerchantProfile
- state.payment_provider_by_id(provider_id) -> Arc<dyn PaymentProvider>
Add a cache provider_cache: Cache<String, Arc<dyn PaymentProvider>> keyed by provider id; invalidated on connect/disconnect/edit.

Call sites that switch:

src/api/purchase.rs — resolve product → profile, then accept a rail selection from the request body (or default to "first rail" if product has no override), then build the provider; pass merchant_profile_id AND payment_provider_id to subscription create.
src/api/upgrade.rs — derive from license → product → profile; pick the same rail the original sub used (snapshot).
src/subscriptions.rs — use sub.payment_provider_id snapshot (already planned in the prior multi-provider draft); additionally use sub.merchant_profile_id to load redirect URL / branding for the renewal webhook payload.
src/tipping.rs, src/reconcile.rs — same pattern.

src/api/webhook.rs — router unchanged from the prior multi-provider draft: /v1/{kind}/webhook/{provider_id} is still the path. The provider_id resolves to a profile transitively, and the webhook handler doesn't need to know about profiles (it just needs to validate the payload against the right provider's secret and update the right invoice).

src/api/btcpay_authorize.rs and src/api/zaprite_authorize.rs — connect flows:

Connect now takes a merchant_profile_id query param. Default = the default profile if not specified.
Refuses if a provider of the same kind already exists on that profile (the unique index would error; we want a clean 409 with a helpful message: "Recaps already has a Zaprite provider — disconnect it first or connect to a different profile").
"Disconnect" deletes the provider row; if it was the last provider on the profile AND that profile has active products/subscriptions, the admin UI prompt requires picking a replacement before delete.
New endpoint POST /v1/admin/merchant-profiles/{id} CRUD endpoints for profile management.

Subscription snapshot semantics

subscriptions.merchant_profile_id AND subscriptions.payment_provider_id are both set on create and never changed by product edits. If the operator later moves a product to a different merchant profile:

New purchases on that product create subscriptions tied to the NEW profile + provider.
Existing subscriptions keep renewing through their ORIGINAL profile + provider.
Trade-off: an admin "re-route this subscription" action exists as a manual flow (see "Mid-cycle subscription migration" in future considerations) — never automatic.

Admin UI changes (in `web/index.html`)

Settings → Merchant Profiles (new top-level page)

List view: table of profiles with name, default badge, attached provider kinds (icons for BTCPay / Zaprite), product count, action menu (edit, set default, delete).
"Add Merchant Profile" button: tier-gated. On Creator with 1 profile, the button shows the tier-cap upgrade modal instead.
Profile edit page: form with all the merchant_profile fields. Section for "Payment providers" listing attached providers with disconnect/ reconnect; "Connect BTCPay" and "Connect Zaprite" buttons within the profile (which is how the connect flow's merchant_profile_id query param gets populated). Section for optional per-profile SMTP override (collapsed by default; the keysat-smtp-emails plan covers the form fields in detail).
Delete profile: refused if the profile has any active products or unsettled subscriptions; otherwise prompts confirm.

Existing Payment Providers page (rename → drop)

The current "Payment Providers" section on the Settings page is removed; provider config now lives INSIDE each merchant profile's edit page. There's no top-level "list all providers across all profiles" view — providers are scoped to their profile.

Product create/edit page

New "Settle through" picker:
- "Merchant profile" dropdown — required, defaults to the default profile. Lists all profiles the operator has configured.
- Below it, an info chip showing which payment rails buyers will be offered ("Card via Zaprite + Lightning via BTCPay") based on the chosen profile's attached providers. If the profile has no providers, the operator sees an error: "This merchant profile has no payment providers connected — buyers can't pay until you add one."

Buy page (`/buy/<slug>`)

Brand block at top renders the merchant profile's name, optionally with brand_color accent, and "Sold by {name}" subtitle.
Existing tier-card UI unchanged except for the payment-method picker: if the profile has 2+ providers, render a "Pay with" picker (Card / Lightning / Bitcoin) before the final Pay button. If only 1 provider, hide the picker (current behavior).
After payment, redirect respects profile's post_purchase_redirect_url if set; falls back to Keysat's default thank-you page.

Files modified (estimated)

migrations/0020_merchant_profiles.sql (new)
src/merchant_profiles.rs (new)
src/payment/mod.rs — provider factory + rail concept + profile-aware accessors
src/payment/btcpay.rs, src/payment/zaprite/{client,config,provider}.rs — constructors take row config; declare rails
src/api/{purchase,upgrade,webhook,btcpay_authorize,zaprite_authorize, merchant_profiles}.rs — call sites + new CRUD endpoints
src/api/mod.rs (AppState) — provider cache + profile accessors
src/db/repo.rs — profile + provider repo helpers
src/subscriptions.rs — snapshot profile_id + provider_id
src/tier.rs — wire unlimited_merchant_profiles entitlement
src/tipping.rs, src/reconcile.rs — pass profile context
web/index.html — new Merchant Profiles section + product picker + buy-page profile branding + payment-method picker
startos/versions/v0.2.0.ts — bump (TBD which :NN), release notes flagging one-way migration + Creator tier cap

Verification

Unit/integration tests: profile CRUD with tier gating (Creator hits cap, Pro/Patron doesn't); subscription snapshot stickiness across product moves; provider-by-rail resolution.
Migration test: copy a production-shape DB (BTCPay singleton + one product + one active sub + active_provider setting), run migrations, confirm: one default profile exists named per operator, one BTCPay provider attached, product points to default profile, sub points to both default profile + the migrated BTCPay provider.
Sandbox end-to-end:
- On a Pro-tier instance, create two profiles: "Recaps" and "Keysat".
- Connect a Zaprite sandbox org to Recaps; connect a different Zaprite sandbox org to Keysat.
- Create a Recaps product, attach to Recaps profile. Create a Keysat product, attach to Keysat profile.
- Buy each. Confirm:
  - Recaps purchase shows "Sold by Recaps" branding on buy page, redirects to Recaps's post_purchase_redirect_url, settles to the Recaps Zaprite dashboard, webhook hits /v1/zaprite/webhook/{recaps-provider-id}.
  - Keysat purchase shows Keysat branding, redirects to Keysat thank-you, settles to Keysat Zaprite dashboard.
Multi-rail per profile:
- On the Recaps profile, also connect BTCPay (separate provider).
- Buy the Recaps product again. Buy page now shows "Pay with Card" and "Pay with Lightning" picker.
- Pick card → Zaprite. Pick Lightning → BTCPay. Confirm each settles to the correct dashboard.
Creator tier cap:
- On a Creator-tier instance, attempt to create a second profile.
- Expect 402 + upgrade modal pointing at the master Keysat upgrade URL.
Backward-compat smoke:
- Existing operator upgrades from :45 to this version. Confirm they see one profile auto-created with their existing operator name + connected providers attached + all products + subs linked through.
- Webhook delivered to OLD /v1/zaprite/webhook URL (no provider id) still settles via the migrated default provider.

Sequencing

This is a bigger change than the original multi-provider draft. Feasible in one cycle but the admin UI surface is meaningful. Two reasonable options:

Option A — single cut. All schema + Rust + admin UI in one release. Cleaner UX (no half-shipped intermediate states) but a heavier cut. Estimate: 2–3 focused days.

Option B — two cuts.

Cut 1: Schema migration + Rust resolution layer + buy-page resolution. Admin UI stays mostly unchanged (one auto-created profile, existing payment providers page shows the default profile's providers). Lower risk; existing operators see no UX change.
Cut 2: Full admin UI surface (Merchant Profiles top-level page, per-profile connect flows, profile picker on product page). Layered on after Cut 1 is stable.

I'd lean toward B — the data-model and resolution-layer changes deserve their own focused cycle, and the UI work benefits from real operator feedback on the new shape before we commit to the admin UX.

Future considerations — still on the roadmap

The merchant-profile shape makes most of these straight extensions. Listed roughly in order of "smallest leap from this foundation."

1. Buyer-currency routing — natively supported

What this plan already does. A profile with multiple providers already exposes a multi-rail picker on the buy page. Currency routing is the same shape: buyer picks USD → routes through the profile's card-capable provider (Zaprite); picks BTC → routes through Bitcoin-capable (BTCPay). No follow-up work needed beyond the multi-rail picker.

What's left for a polish pass. Currency-aware tier card pricing (if a product is listed in USD but the buyer picks BTC, show the sat-equivalent live). Already partly there with the multi-currency work in v0.1.0:43+; the remaining piece is the buy-page rate display.

2. Per-policy provider — "free tier no payment, paid tiers via Stripe"

Value. A product with Free, Pro $5/mo and Patron 50000 sats/mo policies could route the paid policies through different providers. Free tier has no provider at all (today it falls through to whichever is configured + a $0 invoice).

What changes from this plan's foundation. Add a nullable payment_provider_id to policies (a SECOND override). Resolution order: policy override → product's profile → buyer's rail pick.

Complexity. Mostly UI (the policy edit modal gets a "settle through" picker). Half a day on top of this foundation. Probably not needed for v1 — the per-profile-multi-provider model handles most cases.

3. Mid-cycle subscription migration — "move my subs to a new merchant"

Value. Operator changes payment processors (e.g., switches a profile's Zaprite org) and wants existing recurring subs to re-attach to the new provider/profile.

What changes from this plan's foundation. New admin endpoint POST /v1/admin/subscriptions/{id}/migrate that updates the sub's merchant_profile_id and/or payment_provider_id, drops the captured zaprite_payment_profile_id (which is scoped to the old org), and either prompts the buyer to re-save their card OR issues a one-time invoice on the new provider to capture a fresh profile on settle.

Complexity. The data model is trivial — the hard part is the buyer-communication step. Recommended to defer until a real operator asks. Half a day for endpoint + UI.

4. Auto-failover within a merchant profile

Value. A profile has BTCPay primary + Zaprite warm-standby. If BTCPay's webhook deliveries start failing or its API is unreachable, Keysat automatically routes the next purchase through Zaprite without manual intervention.

What changes. New payment_providers.fallback_provider_id (nullable FK to another provider on the SAME profile). Purchase flow tries the primary; on create_invoice failure (network, 5xx, timeout), retries with the fallback. Health-check loop also pings each provider periodically and records last-known-good status for admin UI.

Complexity. Genuine — failure detection is the hard part. 1–2 days for the naive version, more for proper circuit-breaker logic. Lower priority because most operators tolerate manual intervention for brief outages.

5. Multi-tenant Keysat boxes — "Keysat as a service"

Value. Separate business shape: a SaaS provider runs ONE box that hosts licensing for many INDEPENDENT operators (each with their own merchant profiles, products, customers, branding, auth). Different product than the operator-owned licensing server Keysat is today.

What changes. Almost everything — every table needs a tenant_id (or operator_id), auth becomes per-tenant, the admin UI becomes a tenant-scoped view, etc.

Recommendation. Don't plan against this. If the SaaS shape ever becomes interesting, it's a fork or v2.0 product, not a layered-on feature. The merchant-profile schema we're building IS however a useful foundation IF that pivot happens, because per-tenant billing already maps to per-tenant set-of-merchant-profiles.

The merchant-profile foundation we're shipping in this cycle is deliberately shaped to make 1–3 above straight extensions. 4 is a different kind of work (failure detection, not data model). 5 is a different product.

How this composes with the SMTP / operator-alerts plan

See /Users/macpro/.claude/plans/keysat-smtp-emails.md (companion plan).

Per-profile SMTP override fields (in this migration) replace what the SMTP plan originally placed on products. Email branding is business-level, not product-level, so it belongs on merchant_profiles.
The SMTP plan's "buyer transactional emails" opt-in becomes a per-profile flag (merchant_profiles.keysat_sends_buyer_emails) rather than per-product. Master Keysat's profile defaults it to on; Recaps profile defaults it off (Recaps handles its own buyer emails via webhooks).
The SMTP plan's operator alerts are unchanged — those go to the operator personally (StartOS-level email), independent of merchant profiles.

Migration order: ship this plan first (merchant_profiles table exists), then the SMTP plan layers per-profile SMTP + email settings on top of the new table.

27 KiB Raw Blame History Unescape Escape