neoagent 3.0.1-beta.7 → 3.0.1-beta.8

package/.env.example

@@ -267,3 +267,22 @@ NEOAGENT_SCREEN_RECORDER_RETENTION_DAYS=7
 
 MESHTASTIC_ENABLED=true
 TELNYX_WEBHOOK_TOKEN=
+
+########################################
+# Stripe billing (optional)
+########################################
+
+# Set to true or 1 to enable the billing system. When disabled (default),
+# no billing routes are exposed and no payment UI is shown anywhere.
+# NEOAGENT_BILLING_ENABLED=false
+
+# Stripe API keys — required when billing is enabled.
+# Use test keys (sk_test_...) during development; live keys in production.
+# STRIPE_SECRET_KEY=sk_live_...
+# STRIPE_PUBLISHABLE_KEY=pk_live_...
+
+# Webhook signing secret from your Stripe dashboard (Developers > Webhooks).
+# STRIPE_WEBHOOK_SECRET=whsec_...
+
+# Length of free trial periods in days (default: 14).
+# BILLING_TRIAL_DAYS=14

package/README.md

@@ -61,6 +61,7 @@ service to a network.
 - **It operates real devices.** The agent can use an isolated browser and shell, control an Android device or emulator over ADB, or work through a paired Chrome extension and desktop companion.
 - **Automation can start without a message.** Tasks can run on a schedule or from supported Gmail, Outlook, Slack, Teams, personal WhatsApp, and weather events. Android notifications can also start an agent run.
 - **Agents and users have separate state.** Specialist agents can have their own memory, settings, tools, account assignments, conversations, and task history. Multi-user deployments include administrative account controls and optional email confirmation.
+- **SaaS billing is built in and off by default.** Set `NEOAGENT_BILLING_ENABLED=true` to activate Stripe subscriptions, plan management, free trials, and model access restrictions. When disabled, no payment routes or UI appear anywhere. See [Billing](docs/billing.md).
 - **The same server has several interfaces.** NeoAgent includes web, Android, desktop, and Android launcher clients, messaging bridges, a Chrome extension, and firmware for a supported ESP32-S3 wearable.
 
 ## 🖥️ Interfaces

package/docs/billing.md

@@ -0,0 +1,203 @@
+# Billing
+
+NeoAgent includes an optional Stripe-based billing system for deployments that
+charge users for access. When disabled — the default — no billing routes are
+exposed, no payment UI is shown, and no payment-related information appears
+anywhere in the application.
+
+## Enable billing
+
+Set the following environment variables before starting the server:
+
+```bash
+neoagent env set NEOAGENT_BILLING_ENABLED true
+neoagent env set STRIPE_SECRET_KEY sk_live_...
+neoagent env set STRIPE_PUBLISHABLE_KEY pk_live_...
+neoagent env set STRIPE_WEBHOOK_SECRET whsec_...
+```
+
+Restart the server. The admin dashboard will show a **Billing** navigation
+item and the `/api/billing/*` endpoints will become active.
+
+Use Stripe test keys (`sk_test_...`, `pk_test_...`) during development.
+
+## Subscription plans
+
+Plans are managed in **Admin › Billing › Plans**. Each plan controls:
+
+| Field | Purpose |
+|---|---|
+| Name | Displayed to users in the settings submenu |
+| Price | Stripe price in cents (0 = free) |
+| Billing interval | `month`, `year`, or blank for one-time or free |
+| Stripe Price ID | The `price_...` ID from your Stripe dashboard |
+| 4h token limit | Per-user 4-hour rolling token budget (blank = server default) |
+| Weekly token limit | Per-user 7-day rolling token budget (blank = server default) |
+| Allowed models | Comma-separated model IDs; blank = all models accessible |
+| Features | Marketing feature strings shown on pricing pages |
+
+Token limits are written directly to the user account when a subscription
+becomes active or is updated via webhook. The existing rate-limit enforcement
+in the runtime reads them with no additional configuration.
+
+### Free plan
+
+Create a plan with **Price = 0** to serve as the default for new users. If a
+free plan exists when billing is enabled, every new registration is
+automatically placed on it.
+
+### Model restrictions
+
+If **Allowed models** is non-empty, users on that plan can only use the listed
+model IDs. Models outside the allowlist remain visible in the UI with an
+unavailable status so users understand what upgrading unlocks.
+
+Leave the field blank to allow all configured models on a plan.
+
+## User subscriptions
+
+Users manage their subscription in **Settings › Billing** (Flutter client). From
+there they can:
+
+- View their current plan, status, and next renewal date
+- Upgrade or downgrade through Stripe Checkout
+- Open the Stripe Customer Portal to update a payment method or download invoices
+- Cancel at the end of the current billing period
+
+### Stripe Checkout
+
+When a user selects a paid plan, the server creates a Stripe Checkout session
+and redirects the client to Stripe's hosted payment page. No card data passes
+through NeoAgent.
+
+### Stripe Customer Portal
+
+The Customer Portal is a Stripe-hosted page where users can update their
+payment method, view billing history, and cancel. Configure the portal in your
+[Stripe dashboard](https://dashboard.stripe.com/settings/billing/portal) before
+enabling it.
+
+## Free trials
+
+Enable free trials in **Admin › Billing › Plans** by configuring a Stripe price
+that supports trials, then setting `BILLING_TRIAL_DAYS` to the desired length
+(default: 14 days).
+
+Trials start when a user calls `POST /api/billing/trial` with a plan ID. The
+server runs anti-abuse checks before granting a trial:
+
+| Check | Limit |
+|---|---|
+| IP address | 2 trials per IP per 30 days |
+| Email domain | 3 trials per non-common domain per 30 days |
+| Account age | Account must be at least 1 day old |
+| Device fingerprint | 1 trial per device per 90 days (opaque hash from client) |
+
+The Flutter client is responsible for generating and sending the device
+fingerprint. The server hashes it with SHA-256 before storage — the raw
+fingerprint is never persisted.
+
+## Webhooks
+
+Stripe sends events to `POST /api/billing/webhook`. Register this URL in your
+[Stripe dashboard](https://dashboard.stripe.com/webhooks) under the endpoint
+for your account.
+
+Handled events:
+
+| Event | Effect |
+|---|---|
+| `customer.subscription.created` | Creates a local subscription row |
+| `customer.subscription.updated` | Syncs status, period dates, and token limits |
+| `customer.subscription.deleted` | Marks subscription canceled |
+| `customer.subscription.trial_will_end` | Sends trial-ending email (fires 3 days before) |
+| `invoice.payment_succeeded` | Records payment; sends renewal email on cycle |
+| `invoice.payment_failed` | Records failure; sends payment-failed email |
+
+Events are idempotent — replaying a webhook event produces the same result.
+
+**Required events to enable in Stripe:**
+
+```
+customer.subscription.created
+customer.subscription.updated
+customer.subscription.deleted
+customer.subscription.trial_will_end
+invoice.payment_succeeded
+invoice.payment_failed
+```
+
+### Verifying the webhook locally
+
+Use the Stripe CLI to forward events to a local server during development:
+
+```bash
+stripe listen --forward-to http://localhost:3333/api/billing/webhook
+```
+
+## Email notifications
+
+If [service email](configuration.md#service-email) is configured, users receive
+emails at the following billing events:
+
+| Event | Email |
+|---|---|
+| Trial started | Confirmation with trial end date |
+| Trial ending soon | Reminder 3 days before end |
+| Subscription activated | Welcome to the paid plan |
+| Subscription renewed | Renewal confirmation |
+| Payment failed | Action required with next retry date |
+| Subscription canceled | Cancellation confirmation |
+| Plan changed | Summary of the new plan |
+
+No emails are sent if SMTP is not configured.
+
+## AI context awareness
+
+When billing is enabled, each AI request includes the user's subscription in
+the system prompt:
+
+```
+SUBSCRIPTION: User is on the "Pro" plan, status: active.
+```
+
+Agents and workflows can use this context to adapt their behavior — for
+example, acknowledging feature limitations on a free plan or confirming
+capabilities on a paid one.
+
+## Admin controls
+
+The **Admin › Billing** page provides:
+
+- **Plans**: Create, edit, and deactivate subscription plans
+- **Subscriptions**: Browse all user subscriptions with status filter and
+  pagination; override a user's plan without going through Stripe
+
+Override a user's plan directly from the subscriptions table using the
+**Override** button. This is useful for comped accounts, support escalations,
+or fixing a webhook gap.
+
+## Configuration reference
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `NEOAGENT_BILLING_ENABLED` | `false` | Master on/off switch |
+| `STRIPE_SECRET_KEY` | required | Stripe server-side API key |
+| `STRIPE_PUBLISHABLE_KEY` | required | Stripe client-side key (returned to Flutter) |
+| `STRIPE_WEBHOOK_SECRET` | required | Webhook signing secret from Stripe dashboard |
+| `BILLING_TRIAL_DAYS` | `14` | Free trial length in days |
+
+All variables can be set with `neoagent env set` or added to `~/.neoagent/.env`
+directly. Restart the server after any change.
+
+## Security notes
+
+- NeoAgent stores only Stripe customer IDs and subscription IDs — no card
+  numbers, bank details, or PII beyond what Stripe already holds.
+- Webhook payloads are verified with HMAC-SHA256 using `STRIPE_WEBHOOK_SECRET`
+  before any processing. Requests missing the `stripe-signature` header are
+  rejected with 400.
+- Trial fingerprints are stored as SHA-256 hashes — the raw IP, email domain,
+  and device identifiers are never persisted.
+- All billing routes return 404 when `NEOAGENT_BILLING_ENABLED` is not set,
+  regardless of whether Stripe credentials are present.

package/docs/configuration.md

@@ -97,6 +97,19 @@ reset, email changes, and security notifications.
 | `NEOAGENT_EMAIL_PUBLIC_URL` | Base URL used in email links |
 | `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | Confirmation token lifetime |
 
+## Billing
+
+Billing is disabled by default. See [Billing](billing.md) for the full setup
+guide, webhook configuration, and plan management.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `NEOAGENT_BILLING_ENABLED` | `false` | Enable the Stripe billing system |
+| `STRIPE_SECRET_KEY` | unset | Stripe server-side API key |
+| `STRIPE_PUBLISHABLE_KEY` | unset | Stripe client-side key (returned to clients) |
+| `STRIPE_WEBHOOK_SECRET` | unset | Webhook signing secret |
+| `BILLING_TRIAL_DAYS` | `14` | Free trial length in days |
+
 ## Isolated runtime
 
 | Variable | Purpose |

package/docs/index.md

@@ -45,6 +45,7 @@ Continue with:
 | [Recordings and health](recordings-and-health.md) | Audio transcription and Health Connect |
 | [Skills and MCP](skills.md) | Reusable instructions and external tool servers |
 | [Operations](operations.md) | Updates, backups, logs, and recovery |
+| [Billing](billing.md) | Stripe subscriptions, plans, trials, and webhooks |
 | [Configuration](configuration.md) | Environment and runtime reference |
 | [Why NeoAgent](why-neoagent.md) | Factual comparison with OpenClaw and Hermes |
 

package/lib/schema_migrations.js

@@ -458,6 +458,88 @@ function migrateToolPoliciesAllowAlways(db) {
   `);
 }
 
+function migrateBilling(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS billing_plans (
+      id                  TEXT PRIMARY KEY,
+      name                TEXT NOT NULL,
+      description         TEXT DEFAULT '',
+      price_cents         INTEGER NOT NULL DEFAULT 0,
+      currency            TEXT NOT NULL DEFAULT 'usd',
+      interval            TEXT DEFAULT 'month',
+      stripe_price_id     TEXT,
+      token_limit_4h      INTEGER,
+      token_limit_weekly  INTEGER,
+      allowed_models_json TEXT DEFAULT '[]',
+      features_json       TEXT DEFAULT '[]',
+      is_active           INTEGER DEFAULT 1,
+      sort_order          INTEGER DEFAULT 0,
+      created_at          TEXT DEFAULT (datetime('now')),
+      updated_at          TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS billing_customers (
+      user_id            INTEGER PRIMARY KEY,
+      stripe_customer_id TEXT UNIQUE,
+      created_at         TEXT DEFAULT (datetime('now')),
+      updated_at         TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS user_subscriptions (
+      id                     TEXT PRIMARY KEY,
+      user_id                INTEGER NOT NULL,
+      plan_id                TEXT NOT NULL,
+      stripe_subscription_id TEXT UNIQUE,
+      status                 TEXT NOT NULL,
+      trial_ends_at          TEXT,
+      current_period_start   TEXT,
+      current_period_end     TEXT,
+      cancel_at_period_end   INTEGER DEFAULT 0,
+      canceled_at            TEXT,
+      created_at             TEXT DEFAULT (datetime('now')),
+      updated_at             TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+      FOREIGN KEY (plan_id) REFERENCES billing_plans(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS subscription_events (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      user_id         INTEGER NOT NULL,
+      subscription_id TEXT,
+      event_type      TEXT NOT NULL,
+      stripe_event_id TEXT UNIQUE,
+      payload_json    TEXT DEFAULT '{}',
+      created_at      TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS trial_fingerprints (
+      id               INTEGER PRIMARY KEY AUTOINCREMENT,
+      fingerprint_hash TEXT NOT NULL,
+      fingerprint_type TEXT NOT NULL,
+      user_id          INTEGER,
+      used_at          TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE SET NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_billing_customers_stripe
+      ON billing_customers(stripe_customer_id);
+
+    CREATE INDEX IF NOT EXISTS idx_user_subscriptions_user
+      ON user_subscriptions(user_id, status, updated_at DESC);
+
+    CREATE INDEX IF NOT EXISTS idx_user_subscriptions_stripe
+      ON user_subscriptions(stripe_subscription_id);
+
+    CREATE INDEX IF NOT EXISTS idx_subscription_events_stripe
+      ON subscription_events(stripe_event_id);
+
+    CREATE INDEX IF NOT EXISTS idx_trial_fingerprints_hash
+      ON trial_fingerprints(fingerprint_hash, fingerprint_type);
+  `);
+}
+
 function runSchemaMigrations(db) {
   migrateMemoryEmbeddingIndex(db);
   migrateMemoryProvenance(db);
@@ -469,6 +551,7 @@ function runSchemaMigrations(db) {
   migrateToolPermissions(db);
   migrateApprovalPersistence(db);
   migrateToolPoliciesAllowAlways(db);
+  migrateBilling(db);
 }
 
 module.exports = {
@@ -482,5 +565,6 @@ module.exports = {
   migrateToolPermissions,
   migrateApprovalPersistence,
   migrateToolPoliciesAllowAlways,
+  migrateBilling,
   runSchemaMigrations,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neoagent",
-  "version": "3.0.1-beta.7",
+  "version": "3.0.1-beta.8",
   "description": "Self-hosted AI agent for long-running tasks, automation, messaging, device control, and local memory",
   "license": "AGPL-3.0-only",
   "main": "server/index.js",
@@ -100,6 +100,7 @@
     "remotion": "^4.0.459",
     "sharp": "^0.34.5",
     "socket.io": "^4.8.1",
+    "stripe": "^22.2.1",
     "telegraf": "^4.16.3",
     "telnyx": "^5.51.0",
     "tesseract.js": "^7.0.0",

package/server/admin/admin.js

@@ -16,7 +16,8 @@ function showPage(page, btn) {
   if (btn) btn.classList.add('active');
   currentPage = page;
 
-  const loaders = { overview: loadHealth, logs: loadLogs, issues: loadIssues, updates: loadVersion, config: loadConfig, providers: loadProviders, models: loadModels, analytics: loadAnalytics, users: loadUsers, sql: loadSql, access: loadAccess };
+  const billingLoader = typeof loadBilling !== 'undefined' ? loadBilling : null;
+  const loaders = { overview: loadHealth, logs: loadLogs, issues: loadIssues, updates: loadVersion, config: loadConfig, providers: loadProviders, models: loadModels, analytics: loadAnalytics, users: loadUsers, sql: loadSql, access: loadAccess, billing: billingLoader };
   loaders[page]?.();
 }