Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* What a plan lets a house do, and the one thing no plan may ever stop it doing.
*
* ── The cost model, because it decides the shape of everything below ─────────
*
* The expensive thing in this lane is not an action. It is a HELD SOCKET. A
* house that is connected and idle occupies heap on a Cloud Run instance for
* the entire month whether or not anybody speaks to it, so a plan metered only
* on actions would charge nothing for the dominant cost. That is why `homes`
* is the first dimension here and why it is the one enforced at acquisition.
*
* Measured, not assumed (scripts/measure-home-entitlement-cost.mjs, 2026-09-03,
* 16 real WebSocket connections against a real Home Assistant with 125
* entities, priced against the production service shape and the live Cloud Run
* SKUs from Google's own billing catalog):
*
* 302 KB heap / 262 KB RSS per live connection → $0.0155 per home per month
* 23,036-byte room graph per stream event → $0.0066 per open stream per month
* an agent turn on the default free LLM chain → $0
* the same turn on Claude Sonnet 5 → $0.0228
*
* The finding that number produces is worth stating plainly: **one agent turn on
* a paid model costs weeks of holding that house's socket** ($0.0228 against
* $0.0155 a month, so about six weeks for one sentence). A re-measurement on
* 2026-09-09 reproduced the heap and stream figures and put resident memory
* higher, at $0.0738 per home per month; even there a Sonnet turn is nine days
* of socket, so the shape below holds across the range. See
* docs/home-plans.md. The free
* tier can therefore carry a genuinely connected home, and the limits below are
* generous on connections and careful on paid-model turns, which is the opposite
* of what the cost model looked like before it was measured.
*
* ── The five commitments ─────────────────────────────────────────────────────
*
* These are product commitments, not implementation details, and the first and
* last are the ones to fight for if anybody pushes back:
*
* 1. A LIMIT NEVER BLOCKS A SAFETY ACTION. Over quota, past due, downgraded,
* suspended: a user can still lock their door, close their garage, close a
* water valve and arm their alarm. The safe direction is always free. A
* product that will not let someone lock up because they hit a quota is
* indefensible, and `isQuotaExempt` below is where that is enforced rather
* than promised. It delegates to the home-bridge package's own
* `isSafetyAction`, so the list of safe moves is a fact about Home
* Assistant kept in one place, never a copy in the billing code.
*
* 2. DOWNGRADING NEVER SILENTLY DISCONNECTS A HOUSE. Connections over the new
* limit are marked inactive with a written explanation and the user picks
* which to keep. Nothing is deleted, no credential is scrubbed, no action
* log loses its lineage. See `planDowngrade` and `applyDowngrade`.
*
* 3. A QUOTA IS SHOWN BEFORE IT IS HIT, on the manage surface, with the reset
* date. `describeEntitlements` returns exactly what that surface renders.
*
* 4. ENTERPRISE LIMITS ARE CONFIGURABLE PER ACCOUNT, not hardcoded, because
* that is what the sales conversation is. `home_plan_overrides` carries
* them and raising one is a row, never a deploy.
*
* 5. NOTHING ABOUT THE GATE IS A PAID FEATURE. Confirmations, the audit log's
* integrity and the role system's safety properties exist on every tier.
* Selling safety would be wrong and it would also make the free tier a
* liability. There is deliberately no dimension below for any of them, and
* there must never be one.
*
* ── Where the numbers come from ──────────────────────────────────────────────
*
* This module does NOT invent a fourth entitlement system. It reads the two that
* already exist:
*
* api/_lib/account-tier.js the membership modes (user, beta, pro, holder,
* three-dimensional) and the resolver over them.
* api/_lib/three-tier.js the $THREE holder ladder and its `rateMultiplier`,
* which is already defined as "scales free quotas".
*
* A member wears several badges at once, so a limit is the MAX across every
* active badge, never the primary badge's alone: a Pro subscriber who also holds
* $THREE must not lose Pro's connection limit because `holder` outranks `pro`.
*
* Every number is env-overridable (`HOME_LIMIT_<TIER>_<DIMENSION>`), so applying
* an owner-approved price is a config change on a running service and not a
* deploy. The defaults below are a PROPOSAL: see docs/home-plans.md.
*/
import { isSafetyAction, isSafetyMcpCall } from '@three-ws/home-bridge';
import { detectHolder, resolveAccountTier } from '../account-tier.js';
import { sql } from '../db.js';
import { withDbRetry } from '../db-retry.js';
import { tierForUsd } from '../three-tier.js';
/** No limit. Chosen over `null` so a comparison never silently passes on a typo. */
export const UNLIMITED = Number.POSITIVE_INFINITY;
/**
* The dimensions we meter, each with the measured cost that justifies metering
* it at all. A dimension without a cost behind it is a dimension we should not
* be charging for, so `costPerUnitUsd` is required and `costBasis` says how it
* was read.
*
* `scalesWithHolding` marks the dimensions the $THREE ladder's `rateMultiplier`
* applies to. Structural, sold-not-held dimensions (household members) are
* deliberately excluded: holding a bag is not the same purchase as buying seats
* for a hotel, and multiplying one by the other prices neither correctly.
*/
export const HOME_DIMENSIONS = Object.freeze({
homes: Object.freeze({
id: 'homes',
label: 'Connected homes',
unit: 'home',
scope: 'account',
period: 'concurrent',
scalesWithHolding: true,
costPerUnitUsd: 0.0155,
costBasis: 'per month; 302 KB heap / 262 KB RSS per live WebSocket, 16 connections against a real Home Assistant, priced on the production 4 GiB / 2 vCPU shape at the live us-central1 Cloud Run rate',
why: 'A connected house holds a socket for the whole month whether or not anyone speaks to it. This is the lane’s primary cost.',
}),
members: Object.freeze({
id: 'members',
label: 'Household members per home',
unit: 'member',
scope: 'home',
period: 'concurrent',
scalesWithHolding: false,
costPerUnitUsd: 0,
costBasis: 'no marginal infrastructure cost; a member is a row in home_members and shares the home’s single pooled socket',
why: 'The enterprise dimension. A hotel or an office buys seats, and seats are the sales conversation, not a compute cost.',
}),
streams: Object.freeze({
id: 'streams',
label: 'Live streams per home',
unit: 'stream',
scope: 'home',
period: 'concurrent',
scalesWithHolding: true,
costPerUnitUsd: 0.0066,
costBasis: 'per month; a 23,036-byte room graph serialized once per 10 s, priced at the live us-central1 Cloud Run CPU and memory rates',
why: 'A wall display left open all month is a subscriber we serialize the house to on every state change.',
}),
voiceMinutes: Object.freeze({
id: 'voiceMinutes',
label: 'Voice minutes',
unit: 'minute',
scope: 'account',
period: 'month',
scalesWithHolding: true,
costPerUnitUsd: 0,
costBasis: 'the default lanes are keyless: Edge Read Aloud TTS (api/_lib/tts-edge.js) and NVIDIA Riva ASR (api/_lib/asr-nvidia.js) both cost the platform nothing per utterance',
why: 'Metered because a paid speech lane can be selected and because an unbounded always-listening satellite is an abuse surface, not because the default lane costs money.',
}),
agentTurns: Object.freeze({
id: 'agentTurns',
label: 'Agent turns',
unit: 'turn',
scope: 'account',
period: 'month',
scalesWithHolding: true,
costPerUnitUsd: 0,
costBasis: 'the default provider chain leads with platform-held free lanes (isFreeLane in api/_lib/llm-pricing.js); the same 6,359-token home prompt costs $0.0025 on Vertex Gemini 2.5 Flash and $0.0228 on Claude Sonnet 5 when a paid model is chosen',
why: 'The room graph makes a home prompt large. On a paid model one turn costs weeks of holding that house’s socket, so the turn is the dimension that actually needs a ceiling.',
}),
logRetentionDays: Object.freeze({
id: 'logRetentionDays',
label: 'Action-log retention',
unit: 'day',
scope: 'account',
period: 'retention',
scalesWithHolding: true,
costPerUnitUsd: 0,
costBasis: 'Neon row storage; a busy evening of voice control is a few dozen rows of a few hundred bytes each',
why: 'A natural enterprise upsell: a hotel needs a year of attribution, a household needs last Tuesday. Length is the product, never the log’s integrity.',
// A CEILING on what a user may set, never a value of its own. Order 15
// (api/_lib/home/privacy.js) owns the per-home retention setting, its
// default of 90 days and the purge that enforces it; this only caps how
// high that setting may go. It is checked when the user changes the
// setting and NEVER applied retroactively: shortening somebody's existing
// audit trail for a billing reason would destroy their evidence, which is
// the log's integrity, which commitment 5 puts out of reach of a plan.
ceilingOnly: true,
}),
relayConnections: Object.freeze({
id: 'relayConnections',
label: 'Relay connections',
unit: 'relay',
scope: 'account',
period: 'concurrent',
scalesWithHolding: true,
costPerUnitUsd: 0.0155,
costBasis: 'the same held-socket cost as a direct home; a relay is an inbound socket instead of an outbound one',
why: 'A LAN-only house reaches us through a sustained dial-out tunnel, which costs what a direct connection costs.',
}),
});
/** Dimension ids, in the order the manage surface renders them. */
export const HOME_DIMENSION_IDS = Object.freeze(Object.keys(HOME_DIMENSIONS));
/**
* The proposed defaults, per account-tier badge.
*
* PROPOSAL, not a decision. The mechanism is complete and every number here is
* a config value: `HOME_LIMIT_PRO_HOMES=25` on the running service raises Pro's
* connection limit with no deploy and no code change. See docs/home-plans.md for
* the table put to the owner and the measured cost behind each row.
*
* The shape follows the cost: connections are cheap so the free tier gets a real
* one, and turns are the dimension where a paid model can actually spend money
* so that is where the tiers separate.
*/
const DEFAULT_LIMITS = Object.freeze({
user: Object.freeze({
homes: 1,
members: 3,
streams: 2,
voiceMinutes: 300,
agentTurns: 1000,
logRetentionDays: 90,
relayConnections: 1,
}),
beta: Object.freeze({
homes: 2,
members: 5,
streams: 3,
voiceMinutes: 600,
agentTurns: 2500,
logRetentionDays: 90,
relayConnections: 1,
}),
pro: Object.freeze({
homes: 5,
members: 15,
streams: 10,
voiceMinutes: 3000,
agentTurns: 15000,
logRetentionDays: 365,
relayConnections: 5,
}),
holder: Object.freeze({
homes: 1,
members: 3,
streams: 2,
voiceMinutes: 300,
agentTurns: 1000,
logRetentionDays: 90,
relayConnections: 1,
}),
'three-dimensional': Object.freeze({
homes: UNLIMITED,
members: UNLIMITED,
streams: UNLIMITED,
voiceMinutes: UNLIMITED,
agentTurns: UNLIMITED,
// Not UNLIMITED: home_connections_retention_days_chk caps the stored value
// at ten years, so an "unlimited" ceiling here would offer a number the
// database refuses. A limit the schema cannot honour is a broken promise.
logRetentionDays: 3650,
relayConnections: UNLIMITED,
}),
});
/**
* `HOME_LIMIT_<TIER>_<DIMENSION>`, upper snake case, e.g.
* `HOME_LIMIT_THREE_DIMENSIONAL_AGENT_TURNS`. `unlimited` and `-1` both mean no
* limit; anything unparseable is ignored so a typo degrades to the default
* rather than to zero, which would lock an account out of its own house.
*/
function envLimit(tierId, dimensionId) {
const key = `HOME_LIMIT_${screamingSnake(tierId)}_${screamingSnake(dimensionId)}`;
const raw = process.env[key];
if (raw == null || String(raw).trim() === '') return null;
return parseLimit(raw);
}
function parseLimit(raw) {
const s = String(raw).trim().toLowerCase();
if (s === 'unlimited' || s === 'infinity' || s === '-1') return UNLIMITED;
const n = Number.parseInt(s, 10);
return Number.isFinite(n) && n >= 0 ? n : null;
}
function screamingSnake(id) {
return String(id)
.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
.replace(/[^A-Za-z0-9]+/g, '_')
.toUpperCase();
}
/**
* The configured limits for one badge, env overrides applied.
* @param {string} tierId
* @returns {Record<string, number>}
*/
export function limitsForTier(tierId) {
const base = DEFAULT_LIMITS[tierId] || DEFAULT_LIMITS.user;
const out = {};
for (const dimension of HOME_DIMENSION_IDS) {
const override = envLimit(tierId, dimension);
out[dimension] = override == null ? base[dimension] : override;
}
return out;
}
/**
* Merge a set of badges into one limit set by taking the max per dimension.
*
* Max, not the primary badge's value, because badges are additive: `holder`
* outranks `pro` on the display ladder, and a Pro subscriber who also holds
* $THREE must not lose Pro's connection limit by buying some of the coin.
*/
function mergeBadgeLimits(badgeIds) {
const merged = {};
for (const dimension of HOME_DIMENSION_IDS) merged[dimension] = 0;
for (const id of badgeIds) {
const limits = limitsForTier(id);
for (const dimension of HOME_DIMENSION_IDS) {
if (limits[dimension] > merged[dimension]) merged[dimension] = limits[dimension];
}
}
return merged;
}
/**
* One account's effective limits, and everything the manage surface needs to
* explain them.
*
* Pure over its inputs so it unit-tests without a wallet RPC or a database:
* `resolveHomeEntitlements` does the I/O and calls this.
*
* @param {{ account_tier?: string|null, plan?: string|null }} user
* @param {object} [opts]
* @param {{ isHolder: boolean, amount: number, usd: number }} [opts.holder]
* @param {Record<string, number>|null} [opts.override] per-account overrides
* @returns {{
* tier: object, badges: object[], holderTier: object, multiplier: number,
* limits: Record<string, number>, sources: Record<string, string>,
* dimensions: object,
* }}
*/
export function computeEntitlements(user, { holder = { isHolder: false, amount: 0, usd: 0 }, override = null } = {}) {
const account = resolveAccountTier(user, { holder });
const badgeIds = account.badges.map((b) => b.id);
const base = mergeBadgeLimits(badgeIds);
// The $THREE ladder already models holding. Read its multiplier; never model
// holding a second time with thresholds of our own.
const holderTier = tierForUsd(holder.usd);
const multiplier = Math.max(1, Number(holderTier.rateMultiplier) || 1);
const limits = {};
const sources = {};
for (const dimension of HOME_DIMENSION_IDS) {
let value = base[dimension];
sources[dimension] = 'plan';
if (HOME_DIMENSIONS[dimension].scalesWithHolding && multiplier > 1 && Number.isFinite(value)) {
value = value * multiplier;
sources[dimension] = 'holder-multiplier';
}
if (override && Object.prototype.hasOwnProperty.call(override, dimension)) {
const parsed = typeof override[dimension] === 'number' ? override[dimension] : parseLimit(override[dimension]);
// An override is the sales conversation, so it wins in both directions:
// an enterprise deal can raise a limit and a fair-use agreement can cap
// one. It is never silently ignored.
if (parsed != null) {
value = parsed;
sources[dimension] = 'account-override';
}
}
limits[dimension] = value;
}
return {
tier: account.primary,
badges: account.badges,
plan: account.plan,
holder,
holderTier,
multiplier,
limits,
sources,
dimensions: HOME_DIMENSIONS,
};
}
/**
* The same thing, with the reads. Resolves the caller's on-chain $THREE standing
* and their per-account override row.
*
* Fails toward the user on every read: an unreachable price oracle resolves a
* holder to the Member floor rather than throwing, and an unreadable override
* row falls back to the plan's limits rather than to zero.
*
* @param {{ id: string, account_tier?: string|null, plan?: string|null }} user
* @param {object} [opts]
* @param {string[]} [opts.walletAddresses]
* @returns {Promise<object>}
*/
export async function resolveHomeEntitlements(user, { walletAddresses = [] } = {}) {
const wallets = walletAddresses.length ? walletAddresses : [user?.wallet_address].filter(Boolean);
const [holder, override] = await Promise.all([
detectHolder(wallets).catch(() => ({ isHolder: false, amount: 0, usd: 0 })),
getAccountOverride(user?.id).catch(() => null),
]);
const resolved = computeEntitlements(user, { holder, override: override?.limits || null });
return { ...resolved, override };
}
/**
* The same thing, from a user id alone, which is what every route actually has.
*
* Reads the account exactly the way /api/users/me/tier already does: the plan
* and grant columns from `users`, plus every Solana wallet the account controls
* (the login wallet and any linked ones), because $THREE may be held in any of
* them and a holder who is only credited for one wallet is a holder we have
* under-served.
*
* @param {string} userId
* @returns {Promise<object>}
*/
export async function resolveHomeEntitlementsForUser(userId) {
const rows = await withDbRetry(() => sql`
select id, plan, account_tier, wallet_address
from users
where id = ${userId} and deleted_at is null
limit 1
`);
const user = rows[0];
if (!user) throw new Error('resolveHomeEntitlementsForUser: no such account');
const linked = await withDbRetry(() => sql`
select address from user_wallets
where user_id = ${userId} and chain_type = 'solana'
`).catch(() => []);
const wallets = [user.wallet_address, ...linked.map((w) => w.address)].filter(Boolean);
return resolveHomeEntitlements(user, { walletAddresses: wallets });
}
/**
* The account's limits WITHOUT reading the chain: the floor below which no
* holder standing can matter.
*
* `detectHolder` is an on-chain balance read. It is 60-second cached and it is
* fine on a page load, but the agent-turn gate runs inside a chat turn, and
* putting a Solana RPC on that path to answer a question that is almost always
* "yes, obviously" would be a real latency regression for every user who talks
* to their house.
*
* It is skippable because of an ordering property in `computeEntitlements`: the
* holder multiplier is `Math.max(1, ...)`, so it only ever RAISES a limit, and a
* per-account override is applied AFTER it and therefore lands identically in
* both paths. So this floor is always less than or equal to the real limit, and
* a caller that is inside the floor is inside the real limit too. A caller that
* is NOT inside the floor has to do the full read, because that is exactly the
* account whose holding might be the thing that saves them.
*
* @param {string} userId
* @returns {Promise<object>} the same shape as resolveHomeEntitlements, holder-free
*/
export async function resolveHomeEntitlementsFloor(userId) {
const rows = await withDbRetry(() => sql`
select id, plan, account_tier, wallet_address
from users
where id = ${userId} and deleted_at is null
limit 1
`);
const user = rows[0];
if (!user) throw new Error('resolveHomeEntitlementsFloor: no such account');
const override = await getAccountOverride(userId).catch(() => null);
const resolved = computeEntitlements(user, { override: override?.limits || null });
return { ...resolved, override };
}
// ── Per-account overrides ────────────────────────────────────────────────────
/**
* The enterprise row. One per account, set by an admin, with the reason on it,
* because "why does this account have 400 homes" is a question somebody asks six
* months later and the answer has to be in the row rather than in a memory.
*
* @param {string} userId
* @returns {Promise<{ limits: Record<string, number>, note: string|null, setBy: string|null, updatedAt: string }|null>}
*/
export async function getAccountOverride(userId) {
if (!userId) return null;
const rows = await withDbRetry(() => sql`
select limits, note, set_by, updated_at
from home_plan_overrides
where user_id = ${userId}
`);
if (!rows.length) return null;
return {
limits: rows[0].limits || {},
note: rows[0].note || null,
setBy: rows[0].set_by || null,
updatedAt: rows[0].updated_at,
};
}
/**
* Write or replace an account's override. Only known dimensions survive, so a
* typo in an admin form cannot install a limit nothing reads.
*
* @param {object} input
* @param {string} input.userId
* @param {Record<string, number|string>} input.limits
* @param {string|null} [input.note] why this account has these limits
* @param {string|null} [input.setBy] the admin's user id
*/
export async function setAccountOverride({ userId, limits, note = null, setBy = null }) {
if (!userId) throw new Error('setAccountOverride: userId is required');
const clean = {};
for (const [key, value] of Object.entries(limits || {})) {
if (!HOME_DIMENSIONS[key]) continue;
const parsed = typeof value === 'number' && Number.isFinite(value) ? value : parseLimit(value);
if (parsed != null) clean[key] = parsed === UNLIMITED ? 'unlimited' : parsed;
}
const rows = await withDbRetry(() => sql`
insert into home_plan_overrides (user_id, limits, note, set_by)
values (${userId}, ${JSON.stringify(clean)}::jsonb, ${note}, ${setBy})
on conflict (user_id) do update set
limits = excluded.limits,
note = excluded.note,
set_by = excluded.set_by,
updated_at = now()
returning limits, note, set_by, updated_at
`);
return rows[0];
}
/** Remove an account's override, returning it to its plan's limits. */
export async function clearAccountOverride(userId) {
if (!userId) return false;
const rows = await withDbRetry(() => sql`
delete from home_plan_overrides where user_id = ${userId} returning user_id
`);
return rows.length > 0;
}
// ── The safety exemption ─────────────────────────────────────────────────────
/**
* Is this call one no commercial limit may ever refuse?
*
* COMMITMENT 1 LIVES HERE. Every enforcement point in the lane calls this first
* and returns without consulting a counter when it answers true. There is no
* tier, no override, no past-due state and no suspension in which locking a
* door, closing a garage, closing a water valve or arming an alarm is refused
* by this platform.
*
* The list of safe moves is NOT duplicated here. It comes from
* `@three-ws/home-bridge`'s `isSafetyAction`, beside the gate it mirrors,
* because what a lock can do is a fact about Home Assistant and not a fact about
* a price list.
*
* @param {object} call
* @param {string} [call.domain]
* @param {string} [call.service]
* @param {object} [call.attributes]
* @param {string} [call.tool] an MCP tool name, when the call arrives on that channel
* @param {object} [call.arguments] the MCP tool's arguments
* @param {Array<object>} [call.entities] the live entity list, for MCP target resolution
* @returns {boolean}
*/
export function isQuotaExempt(call = {}) {
if (call.tool) return isSafetyMcpCall(call.tool, call.arguments || {}, call.entities || []);
return isSafetyAction({ domain: call.domain, service: call.service, attributes: call.attributes || {} });
}
// ── Enforcement ──────────────────────────────────────────────────────────────
/**
* A refusal a user can act on. Never a 500, never a bare "quota exceeded": it
* names the limit, what they are using, when it resets, and what to do next.
*/
export class HomeQuotaError extends Error {
/**
* @param {object} input
* @param {string} input.dimension
* @param {number} input.limit
* @param {number} input.used
* @param {string|null} [input.resetAt]
* @param {object} [input.tier]
* @param {string} [input.message]
*/
constructor({ dimension, limit, used, resetAt = null, tier = null, message = null }) {
const meta = HOME_DIMENSIONS[dimension];
super(message || defaultQuotaMessage({ dimension, limit, used, resetAt, tier }));
this.name = 'HomeQuotaError';
this.code = 'quota_exceeded';
this.status = 402;
this.dimension = dimension;
this.dimensionLabel = meta?.label || dimension;
this.limit = limit;
this.used = used;
this.resetAt = resetAt;
this.tierId = tier?.id || null;
this.upgradePath = '/pricing';
}
}
function defaultQuotaMessage({ dimension, limit, used, resetAt, tier }) {
const meta = HOME_DIMENSIONS[dimension];
const label = (meta?.label || dimension).toLowerCase();
const plan = tier?.label ? `Your ${tier.label} plan` : 'Your plan';
const head = `${plan} covers ${limit} ${limit === 1 ? meta?.unit || label : plural(meta?.unit || label)}, and you are using ${used}.`;
const tail = resetAt
? `This resets on ${formatResetDate(resetAt)}. You can upgrade at three.ws/pricing to raise it now.`
: 'Upgrade at three.ws/pricing to raise it, or free one up on your homes page.';
const safe = 'Locking up, closing a garage or valve and arming an alarm are never affected by a limit.';
return `${head} ${tail} ${safe}`;
}
function plural(unit) {
return /s$/.test(unit) ? unit : `${unit}s`;
}
function formatResetDate(iso) {
const d = new Date(iso);
if (Number.isNaN(d.getTime())) return 'the start of next month';
return d.toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric', timeZone: 'UTC' });
}
/**
* The one enforcement primitive. Every call site in the lane goes through it so
* the safety exemption cannot be forgotten at one of them.
*
* @param {object} input
* @param {object} input.entitlements from resolveHomeEntitlements
* @param {string} input.dimension
* @param {number} input.used current usage, exclusive of the request being made
* @param {number} [input.cost] how many units this request consumes
* @param {string|null} [input.resetAt]
* @param {object|null} [input.call] the physical call, when there is one
* @returns {{ allowed: true, exempt: boolean, remaining: number }}
* @throws {HomeQuotaError}
*/
export function assertWithinLimit({ entitlements, dimension, used, cost = 1, resetAt = null, call = null }) {
if (call && isQuotaExempt(call)) {
return { allowed: true, exempt: true, remaining: Number.POSITIVE_INFINITY };
}
const limit = entitlements?.limits?.[dimension];
if (limit == null) throw new Error(`assertWithinLimit: unknown dimension "${dimension}"`);
if (!Number.isFinite(limit)) return { allowed: true, exempt: false, remaining: Number.POSITIVE_INFINITY };
if (used + cost > limit) {
throw new HomeQuotaError({ dimension, limit, used, resetAt, tier: entitlements.tier });
}
return { allowed: true, exempt: false, remaining: limit - used - cost };
}
/**
* A paused home is not a broken home. It is a home the account's plan does not
* currently cover, and the distinction is the whole of commitment 2: the row is
* intact, the credential is intact, the log is intact, and the user can bring it
* back by upgrading, by pausing a different house, or by changing their mind.
*/
export class HomePausedError extends Error {
/**
* @param {object} input
* @param {string} input.label
* @param {string|null} [input.reason]
*/
constructor({ label, reason = null }) {
super(
`"${label}" is paused because your plan covers fewer connected homes than you have. ` +
`${reason ? `${reason} ` : ''}` +
'Nothing was deleted and nothing was disconnected: bring it back from your homes page, or pause a different home to make room. ' +
'Locking up, closing a garage or valve and arming an alarm keep working on a paused home.',
);
this.name = 'HomePausedError';
this.code = 'home_paused';
this.status = 402;
this.label = label;
this.reason = reason;
this.upgradePath = '/pricing';
}
}
/**
* The guard every action goes through, and the one place commitment 1 is
* enforced on the write path.
*
* Order matters and it is the point: the safety exemption is checked FIRST, so
* there is no plan state, no pause, no quota and no override in which locking a
* door, closing a garage or a valve, or arming an alarm is refused. It is
* checked before the home's state is even looked at, so a bug in the pause logic
* cannot reach it.
*
* The exemption does not need a live socket. `isSafetyAction` classifies from
* the domain and service alone, which is what makes this usable in exactly the
* degraded states where a person most needs to lock up.
*
* @param {object} input
* @param {{ label: string, deactivated_at?: string|null, deactivated_reason?: string|null }} input.home
* @param {{ domain?: string, service?: string, tool?: string, arguments?: object, entities?: object[] }} input.call
* @returns {{ allowed: true, exempt: boolean }}
* @throws {HomePausedError}
*/
export function assertHomeActionAllowed({ home, call }) {
if (isQuotaExempt(call)) return { allowed: true, exempt: true };
if (home?.deactivated_at) {
throw new HomePausedError({ label: home.label || 'This home', reason: home.deactivated_reason });
}
return { allowed: true, exempt: false };
}
/**
* Can this home take another household member?
*
* Billed to the HOME'S OWNER, never to the person sending the invitation. An
* admin inviting a house sitter is spending the owner's seats, and charging the
* admin's own plan for them would mean a household's capacity changed depending
* on which member happened to click the button.
*
* Counts the seats already taken plus the invitations already outstanding,
* because an unspent invite is a seat that is about to be occupied and letting
* ten of them through to a five-seat home just moves the refusal to the moment
* somebody accepts, which is the worst possible time to discover it.
*
* @param {string} homeId
* @returns {Promise<{ allowed: true, remaining: number }>}
* @throws {HomeQuotaError}
*/
export async function assertMemberCapacity(homeId) {
const rows = await withDbRetry(() => sql`
select
c.user_id as owner_id,
(select count(*)::int from home_members m where m.home_id = c.id) as members,
(select count(*)::int from home_invites i
where i.home_id = c.id and i.accepted_at is null and i.revoked_at is null and i.expires_at > now())
as pending
from home_connections c
where c.id = ${homeId}
`);
const row = rows[0];
if (!row) throw new Error('assertMemberCapacity: no such home');
const entitlements = await resolveHomeEntitlementsForUser(row.owner_id);
return assertWithinLimit({
entitlements,
dimension: 'members',
used: (row.members ?? 0) + (row.pending ?? 0),
});
}
// ── The downgrade path ───────────────────────────────────────────────────────
/**
* What a downgrade would do, without doing it.
*
* COMMITMENT 2 LIVES HERE. A downgrade never picks for the user and never
* deletes: it names which homes exceed the new limit, keeps the oldest ones
* active by default because they are the ones most likely to be the real house,
* and hands the choice back.
*
* @param {Array<{ id: string, label: string, created_at: string, deactivated_at?: string|null }>} connections
* @param {number} limit the new connection limit
* @returns {{ overBy: number, limit: number, keep: object[], deactivate: object[], explanation: string }}
*/
export function planDowngrade(connections, limit) {
const live = connections.filter((c) => !c.deactivated_at);
if (!Number.isFinite(limit) || live.length <= limit) {
return { overBy: 0, limit, keep: live, deactivate: [], explanation: '' };
}
const ordered = [...live].sort((a, b) => new Date(a.created_at) - new Date(b.created_at));
const keep = ordered.slice(0, Math.max(0, limit));
const deactivate = ordered.slice(Math.max(0, limit));
const explanation =
`Your plan now covers ${limit} connected ${limit === 1 ? 'home' : 'homes'} and you have ${live.length}. ` +
`We have paused ${deactivate.map((c) => `"${c.label}"`).join(', ')} rather than disconnecting ${deactivate.length === 1 ? 'it' : 'them'}: ` +
'nothing was deleted, your access tokens and your action logs are untouched, and you can swap which homes are active at any time. ' +
'A paused home still answers safety actions: locking up, closing a garage or valve and arming an alarm keep working.';
return { overBy: deactivate.length, limit, keep, deactivate, explanation };
}
/**
* Carry out a downgrade plan. Marks rows inactive; deletes nothing, revokes
* nothing, scrubs no credential.
*
* @param {object} input
* @param {string} input.userId
* @param {string[]} input.deactivateIds
* @param {string} input.reason
* @returns {Promise<object[]>} the paused rows
*/
export async function applyDowngrade({ userId, deactivateIds, reason }) {
if (!userId || !deactivateIds?.length) return [];
return withDbRetry(() => sql`
update home_connections
set deactivated_at = now(),
deactivated_reason = ${String(reason || 'Paused by a plan change.')},
updated_at = now()
where user_id = ${userId}
and id = any(${deactivateIds}::uuid[])
and revoked_at is null
and deactivated_at is null
returning id, label, deactivated_at, deactivated_reason
`);
}
/**
* Bring a paused home back, refusing when doing so would exceed the limit. The
* user swapping which houses are active is the whole point of pausing rather
* than disconnecting, so this is the other half of commitment 2.
*
* @param {object} input
* @param {string} input.userId
* @param {string} input.homeId
* @param {object} input.entitlements
* @returns {Promise<object>}
*/
export async function reactivateConnection({ userId, homeId, entitlements }) {
const active = await countActiveConnections(userId);
assertWithinLimit({ entitlements, dimension: 'homes', used: active });
const rows = await withDbRetry(() => sql`
update home_connections
set deactivated_at = null, deactivated_reason = null, updated_at = now()
where user_id = ${userId} and id = ${homeId} and revoked_at is null
returning id, label, deactivated_at
`);
if (!rows.length) throw new Error('reactivateConnection: no such home for this account');
return rows[0];
}
/** How many of this account's homes are live right now. The `homes` gauge. */
export async function countActiveConnections(userId) {
if (!userId) return 0;
const rows = await withDbRetry(() => sql`
select count(*)::int as n
from home_connections
where user_id = ${userId} and revoked_at is null and deactivated_at is null
`);
return rows[0]?.n ?? 0;
}
// ── The manage surface's view ────────────────────────────────────────────────
/**
* The quota period. A UTC calendar month.
*
* The platform has no per-user plan billing period to key off (`users.plan` is a
* column, not a subscription with a cycle), and inventing one here would be a
* second billing clock that drifts from whatever the real one turns out to be.
* A calendar month resets on a date every user can predict, it is the same
* choice the per-IP image quota already made one rung down (a UTC day), and when
* a real billing cycle lands this is one function to change.
*
* @param {Date} [now]
* @returns {{ start: Date, end: Date, startIso: string, endIso: string, key: string }}
*/
export function quotaPeriod(now = new Date()) {
const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1, 0, 0, 0, 0));
const end = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0));
return {
start,
end,
startIso: start.toISOString(),
endIso: end.toISOString(),
key: start.toISOString().slice(0, 7),
};
}
/**
* Everything the manage surface renders, in one object.
*
* COMMITMENT 3 LIVES HERE: a quota is shown before it is hit. Every dimension
* comes back whether or not it is close to its ceiling, each with its usage, its
* limit, the percentage, the reset date, and the measured cost that justifies
* metering it, so the page can explain the limit rather than merely enforce it.
*
* Pure: it takes the usage rather than reading it, so the page's numbers and the
* enforcement path's numbers come from one function and cannot disagree.
*
* @param {object} entitlements from resolveHomeEntitlements
* @param {Record<string, number>} usage per-dimension current usage
* @param {object} [opts]
* @param {Date} [opts.now]
* @returns {object}
*/
export function describeEntitlements(entitlements, usage = {}, { now = new Date() } = {}) {
const period = quotaPeriod(now);
const dimensions = HOME_DIMENSION_IDS.map((id) => {
const meta = HOME_DIMENSIONS[id];
const limit = entitlements.limits[id];
const used = Number(usage[id]) || 0;
const unlimited = !Number.isFinite(limit);
return {
id,
label: meta.label,
unit: meta.unit,
scope: meta.scope,
period: meta.period,
why: meta.why,
used,
limit: unlimited ? null : limit,
unlimited,
remaining: unlimited ? null : Math.max(0, limit - used),
percent: unlimited ? 0 : limit === 0 ? 100 : Math.min(100, Math.round((used / limit) * 100)),
exceeded: !unlimited && used > limit,
source: entitlements.sources[id],
// A ceiling dimension is not consumed: sitting at it is the normal,
// healthy state (the retention default IS the free ceiling), so the
// surface must not paint it as "you are out of something".
ceilingOnly: Boolean(meta.ceilingOnly),
resetsAt: meta.period === 'month' ? period.endIso : null,
costPerUnitUsd: meta.costPerUnitUsd,
costBasis: meta.costBasis,
};
});
return {
tier: { id: entitlements.tier.id, label: entitlements.tier.label, color: entitlements.tier.color },
badges: entitlements.badges.map((b) => ({ id: b.id, label: b.label, color: b.color })),
plan: entitlements.plan,
holder: {
isHolder: entitlements.holder.isHolder,
usd: entitlements.holder.usd,
tier: entitlements.holderTier.label,
multiplier: entitlements.multiplier,
},
override: entitlements.override
? { note: entitlements.override.note, updatedAt: entitlements.override.updatedAt, dimensions: Object.keys(entitlements.override.limits || {}) }
: null,
period: { startsAt: period.startIso, resetsAt: period.endIso },
dimensions,
// Stated on the surface itself, not only in this file, because a user
// reading their limits is exactly the person who needs to know which of
// them can never apply to them.
alwaysFree: [
'Locking a door, closing a garage or gate, closing a water valve and arming an alarm are never refused by a limit, on any plan.',
'Confirmation prompts, the action log and every role safety property are on every plan. Safety is not an upgrade.',
],
upgradePath: '/pricing',
};
}