@agentforge-io/core 2.0.24 → 2.1.0

package/dist/services/secrets.service.js

@@ -1,193 +0,0 @@
-"use strict";
-// SecretsService — Phase A platform vault.
-//
-// Resolves secrets in this order (first hit wins):
-//   1. process.env[KEY]   — env vars always trump DB. Lets development /
-//      escape-hatch setups keep working, and protects against a corrupt
-//      DB row taking down the service.
-//   2. af_platform_secrets — encrypted blob, decrypted with MASTER_KEY.
-//
-// Resolution is boot-time only: callers ask for a key, the service
-// resolves once and caches the plaintext in memory. Mutating a row via
-// upsert/delete invalidates that key's cache entry, but adapters that
-// already used the old value (e.g. a Stripe client created at boot)
-// keep running with it until the server restarts. That's by design for
-// Phase A — runtime hot-reload is Phase B.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SecretsService = exports.SecretsError = void 0;
-const crypto_1 = require("./secrets/crypto");
-const known_keys_1 = require("./secrets/known-keys");
-const STATUS = {
-    unknown_key: 400,
-    env_override_active: 409,
-    master_key_missing: 503,
-};
-class SecretsError extends Error {
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'SecretsError';
-        this.status = STATUS[code];
-    }
-}
-exports.SecretsError = SecretsError;
-const noopLogger = {
-    log: () => { },
-    warn: () => { },
-    debug: () => { },
-    error: () => { },
-};
-class SecretsService {
-    constructor(repo, opts = {}) {
-        this.repo = repo;
-        this.cache = new Map();
-        this.logger = opts.logger ?? noopLogger;
-        this.env = opts.env ?? process.env;
-        this.masterKey = opts.masterKey;
-        if (!this.masterKey) {
-            this.logger.warn('[secrets] MASTER_KEY not set — DB-backed secrets are unavailable. ' +
-                'Set MASTER_KEY in the environment to enable the vault.');
-        }
-    }
-    // ─── Read path ───────────────────────────────────────────────────────────
-    /**
-     * Resolve a known key. Returns the plaintext or `undefined` when neither
-     * env nor DB has it set. Callers decide whether undefined is fatal (it
-     * is for ANTHROPIC_API_KEY; it's not for TAVILY_API_KEY).
-     *
-     * Cached in memory after first read. Cache survives until the next
-     * upsert/delete on the same key.
-     */
-    async resolve(key) {
-        if (!(0, known_keys_1.isKnownSecretKey)(key)) {
-            // Don't throw — resolve() is on the hot path. Just log + miss.
-            this.logger.warn(`[secrets] resolve("${key}") — unknown key, ignoring`);
-            return undefined;
-        }
-        const cached = this.cache.get(key);
-        if (cached !== undefined)
-            return cached;
-        const envValue = this.env[key];
-        if (envValue) {
-            this.cache.set(key, envValue);
-            return envValue;
-        }
-        if (!this.masterKey)
-            return undefined;
-        const row = await this.repo.findByKey(key);
-        if (!row)
-            return undefined;
-        try {
-            const plaintext = (0, crypto_1.decrypt)(row.valueEncrypted, this.masterKey);
-            this.cache.set(key, plaintext);
-            return plaintext;
-        }
-        catch (err) {
-            const code = err instanceof crypto_1.SecretCryptoError ? err.code : 'unknown';
-            this.logger.error(`[secrets] decrypt("${key}") failed (${code}). ` +
-                `Master key was likely rotated without re-encrypting; ` +
-                `the operator must re-enter this secret.`);
-            return undefined;
-        }
-    }
-    /**
-     * Bulk variant — resolve every known key at once. Useful at boot when
-     * the server wants to decide which adapters to wire up (Stripe on/off,
-     * which search provider, etc.). Skips logging on individual misses to
-     * keep the boot log readable.
-     */
-    async resolveAll() {
-        const out = {};
-        for (const def of (0, known_keys_1.listKnownSecrets)()) {
-            const value = await this.resolve(def.key);
-            if (value)
-                out[def.key] = value;
-        }
-        return out;
-    }
-    // ─── Admin path ──────────────────────────────────────────────────────────
-    /**
-     * Admin-facing catalog. Returns one entry per known key — including
-     * the ones that aren't configured anywhere — so the UI can render the
-     * whole table in one shot.
-     *
-     * Never returns plaintext or ciphertext: only hint + metadata.
-     */
-    async listForAdmin() {
-        const rows = this.masterKey ? await this.repo.listAll() : [];
-        const byKey = new Map(rows.map((r) => [r.key, r]));
-        return (0, known_keys_1.listKnownSecrets)().map((def) => {
-            const envSet = !!this.env[def.key];
-            const row = byKey.get(def.key);
-            const source = envSet
-                ? 'env'
-                : row
-                    ? 'db'
-                    : 'none';
-            return {
-                key: def.key,
-                description: def.description,
-                sensitivity: def.sensitivity,
-                configured: source !== 'none',
-                source,
-                valueHint: source === 'db' ? row?.valueHint : undefined,
-                updatedAt: source === 'db' ? row?.updatedAt : undefined,
-                updatedByUserId: source === 'db' ? row?.updatedByUserId : undefined,
-            };
-        });
-    }
-    /**
-     * Upsert a known secret. The new ciphertext + hint hit the DB; the
-     * cache entry is evicted so the next `resolve` re-reads (and decrypts)
-     * fresh data. Returns the row metadata so the UI can echo the hint.
-     *
-     * Throws `unknown_key` for keys outside the catalog (no free-form
-     * inserts), `master_key_missing` when MASTER_KEY isn't configured.
-     */
-    async upsert(input) {
-        if (!(0, known_keys_1.isKnownSecretKey)(input.key)) {
-            throw new SecretsError('unknown_key', `"${input.key}" is not a known platform secret. ` +
-                `Known keys: ${(0, known_keys_1.listKnownSecrets)().map((d) => d.key).join(', ')}.`);
-        }
-        if (!this.masterKey) {
-            throw new SecretsError('master_key_missing', 'Cannot write a secret without MASTER_KEY configured.');
-        }
-        const encrypted = (0, crypto_1.encrypt)(input.value, this.masterKey);
-        const hint = (0, crypto_1.valueHint)(input.value);
-        const row = await this.repo.upsert({
-            key: input.key,
-            valueEncrypted: encrypted,
-            valueHint: hint,
-            description: input.description ?? known_keys_1.KNOWN_SECRETS[input.key].description,
-            updatedByUserId: input.updatedByUserId,
-        });
-        this.cache.delete(input.key);
-        return row;
-    }
-    /**
-     * Hard-delete a known secret. Refuses while the matching env var is
-     * set — otherwise the operator would see "still configured" in the UI
-     * after deleting, which is confusing.
-     */
-    async delete(key) {
-        if (!(0, known_keys_1.isKnownSecretKey)(key)) {
-            throw new SecretsError('unknown_key', `Unknown key: ${key}`);
-        }
-        if (this.env[key]) {
-            throw new SecretsError('env_override_active', `Cannot delete "${key}" while the env var is set in the deployment. ` +
-                `Unset it in the .env (or restart with it removed) before deleting from the vault.`);
-        }
-        if (!this.masterKey) {
-            // Without MASTER_KEY the DB is unreadable; deleting is still safe.
-            // We just let it through.
-        }
-        await this.repo.deleteByKey(key);
-        this.cache.delete(key);
-    }
-    /** For tests + admin tools: drop everything from cache so the next
-     *  resolve goes back to env/DB. */
-    clearCache() {
-        this.cache.clear();
-    }
-}
-exports.SecretsService = SecretsService;

package/dist/services/tenant-billing.service.d.ts

@@ -1,121 +0,0 @@
-import type { SubscriptionRepository, TenantRepository, ExternalUserRepository, UsageRecordRepository } from '../repositories';
-import type { IBillingAdapter } from '../adapters/billing/billing-adapter.interface';
-import type { SubscriptionStatus } from '../types/billing.types';
-import type { BillingConfig } from '../types/config.types';
-import type { Plan } from '../domain/plan';
-import type { PlanService } from './plan.service';
-export interface TenantBillingOverview {
-    plan: {
-        id: string;
-        name: string;
-        features: string[];
-        limits: {
-            requestsPerMonth: number;
-            tokensPerMonth: number;
-        };
-        priceInCents?: number;
-        interval?: 'month' | 'year';
-    };
-    usage: {
-        period: string;
-        requestCount: number;
-        totalTokens: number;
-        requestLimit: number;
-        tokenLimit: number;
-    };
-    subscription: {
-        id: string;
-        planId: string;
-        status: SubscriptionStatus;
-        currentPeriodStart?: Date;
-        currentPeriodEnd?: Date;
-        cancelAtPeriodEnd: boolean;
-    } | null;
-}
-export interface TenantCheckoutResult {
-    checkoutUrl: string;
-    sessionId?: string;
-}
-export interface TenantBillingServiceOptions {
-    billing?: BillingConfig;
-    defaultLimits?: {
-        requestsPerMonth?: number;
-        tokensPerMonth?: number;
-    };
-    logger?: {
-        warn: (m: string) => void;
-        log: (m: string) => void;
-    };
-    /** Source of truth for plans (DB-backed in production). */
-    plans: PlanService;
-}
-/**
- * Billing for the B2B path: a Tenant is the payer, its API keys consume the
- * service, and quotas apply to the (aggregated) usage of all external users
- * under that tenant. Mirrors the user-centric BillingService but scoped one
- * level up.
- */
-export declare class TenantBillingService {
-    private readonly tenants;
-    private readonly subscriptions;
-    private readonly usageRecords;
-    private readonly externalUsers;
-    private readonly adapter;
-    private readonly opts;
-    constructor(tenants: TenantRepository, subscriptions: SubscriptionRepository, usageRecords: UsageRecordRepository, externalUsers: ExternalUserRepository, adapter: IBillingAdapter, opts: TenantBillingServiceOptions);
-    getPlans(): Promise<Plan[]>;
-    getPlan(planId: string): Promise<Plan | undefined>;
-    getDefaultPlanId(): Promise<string>;
-    createCheckout(input: {
-        tenantId: string;
-        planId: string;
-        /** Override URLs per request (e.g. coming from a frontend on a custom domain). */
-        successUrl?: string;
-        cancelUrl?: string;
-        appUrl?: string;
-    }): Promise<TenantCheckoutResult>;
-    getPortalUrl(tenantId: string, returnUrl?: string): Promise<{
-        url: string;
-    }>;
-    getOverview(tenantId: string): Promise<TenantBillingOverview>;
-    cancelSubscription(tenantId: string, immediately?: boolean): Promise<void>;
-    /**
-     * Handle a webhook event whose `data.metadata.tenantId` indicates a tenant
-     * subscription. Returns true if handled. The caller should fall through to
-     * the user-centric handler when this returns false.
-     */
-    handleWebhookEvent(event: {
-        type: string;
-        data: Record<string, unknown>;
-    }): Promise<boolean>;
-    private onCheckoutCompleted;
-    private onSubscriptionUpdated;
-    private onSubscriptionDeleted;
-    private onPaymentFailed;
-    /**
-     * Decide whether a tenant is still within its monthly quotas. Designed to be
-     * called on the hot path (every chat request) — does one aggregate query
-     * against `af_usage_records` and one tenant lookup.
-     *
-     * Limits of `-1` mean "unlimited" for that dimension (per plan definition
-     * convention). Returns `{ allowed: false, reason }` when any positive limit
-     * has been reached or exceeded.
-     */
-    checkLimits(tenantId: string): Promise<{
-        allowed: boolean;
-        reason?: string;
-        usage: {
-            period: string;
-            requestCount: number;
-            totalTokens: number;
-            requestLimit: number;
-            tokenLimit: number;
-        };
-    }>;
-    private aggregateTenantUsage;
-}
-export declare class TenantBillingError extends Error {
-    status: number;
-    code: 'not_found' | 'plan_not_found' | 'plan_not_purchasable' | 'no_customer' | 'no_active_subscription';
-    constructor(code: 'not_found' | 'plan_not_found' | 'plan_not_purchasable' | 'no_customer' | 'no_active_subscription', message: string);
-}

package/dist/services/tenant-billing.service.js

@@ -1,290 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TenantBillingError = exports.TenantBillingService = void 0;
-/**
- * Billing for the B2B path: a Tenant is the payer, its API keys consume the
- * service, and quotas apply to the (aggregated) usage of all external users
- * under that tenant. Mirrors the user-centric BillingService but scoped one
- * level up.
- */
-class TenantBillingService {
-    constructor(tenants, subscriptions, usageRecords, externalUsers, adapter, opts) {
-        this.tenants = tenants;
-        this.subscriptions = subscriptions;
-        this.usageRecords = usageRecords;
-        this.externalUsers = externalUsers;
-        this.adapter = adapter;
-        this.opts = opts;
-    }
-    // ─── Plans ─────────────────────────────────────────────────────────────
-    async getPlans() {
-        return this.opts.plans.list();
-    }
-    async getPlan(planId) {
-        return this.opts.plans.getPlan(planId);
-    }
-    async getDefaultPlanId() {
-        return this.opts.plans.getDefaultId();
-    }
-    // ─── Checkout ──────────────────────────────────────────────────────────
-    async createCheckout(input) {
-        const tenant = await this.tenants.findById(input.tenantId);
-        if (!tenant)
-            throw new TenantBillingError('not_found', 'Tenant not found');
-        const plan = await this.getPlan(input.planId);
-        if (!plan)
-            throw new TenantBillingError('plan_not_found', `Plan "${input.planId}" not found`);
-        if (!plan.stripePriceId) {
-            throw new TenantBillingError('plan_not_purchasable', `Plan "${input.planId}" has no stripePriceId`);
-        }
-        // Lazy-create the Stripe customer for the tenant.
-        let customerId = tenant.providerCustomerId;
-        if (!customerId) {
-            customerId = await this.adapter.createCustomer({
-                email: undefined, // tenant doesn't have email; can be passed via metadata
-                name: tenant.name,
-                metadata: { tenantId: tenant.id, ownerUserId: tenant.ownerUserId },
-            });
-            await this.tenants.update(tenant.id, { providerCustomerId: customerId });
-            tenant.providerCustomerId = customerId;
-        }
-        const appUrl = input.appUrl ?? this.opts.billing?.appUrl ?? 'http://localhost:3030';
-        const successUrl = input.successUrl
-            ?? this.opts.billing?.successUrl
-            ?? `${appUrl}/billing/success?session_id={CHECKOUT_SESSION_ID}`;
-        const cancelUrl = input.cancelUrl
-            ?? this.opts.billing?.cancelUrl
-            ?? `${appUrl}/billing/cancel`;
-        const session = await this.adapter.createCheckoutSession({
-            userId: tenant.id, // adapter uses this as a key in metadata
-            planId: input.planId,
-            stripePriceId: plan.stripePriceId,
-            successUrl,
-            cancelUrl,
-            metadata: { tenantId: tenant.id, planId: input.planId },
-        });
-        return { checkoutUrl: session.url, sessionId: session.sessionId };
-    }
-    // ─── Portal ────────────────────────────────────────────────────────────
-    async getPortalUrl(tenantId, returnUrl) {
-        const tenant = await this.tenants.findById(tenantId);
-        if (!tenant)
-            throw new TenantBillingError('not_found', 'Tenant not found');
-        if (!tenant.providerCustomerId) {
-            throw new TenantBillingError('no_customer', 'Tenant has no payment account yet — create a checkout first');
-        }
-        const portalReturn = returnUrl
-            ?? this.opts.billing?.portalReturnUrl
-            ?? `${this.opts.billing?.appUrl ?? 'http://localhost:3030'}/billing`;
-        const url = await this.adapter.getPortalUrl(tenant.providerCustomerId, portalReturn);
-        return { url };
-    }
-    // ─── Overview ──────────────────────────────────────────────────────────
-    async getOverview(tenantId) {
-        const tenant = await this.tenants.findById(tenantId);
-        if (!tenant)
-            throw new TenantBillingError('not_found', 'Tenant not found');
-        const subscription = await this.subscriptions.findActiveForTenant(tenantId);
-        const planId = tenant.planId;
-        const plan = await this.getPlan(planId);
-        const usage = await this.aggregateTenantUsage(tenantId);
-        const requestLimit = plan?.limits.requestsPerMonth
-            ?? this.opts.defaultLimits?.requestsPerMonth
-            ?? -1;
-        const tokenLimit = plan?.limits.tokensPerMonth
-            ?? this.opts.defaultLimits?.tokensPerMonth
-            ?? -1;
-        return {
-            plan: {
-                id: planId,
-                name: plan?.name ?? planId,
-                features: plan?.features ?? [],
-                limits: {
-                    requestsPerMonth: requestLimit,
-                    tokensPerMonth: tokenLimit,
-                },
-                priceInCents: plan?.priceInCents,
-                interval: plan?.interval,
-            },
-            usage: {
-                period: currentBillingPeriod(),
-                requestCount: usage.requestCount,
-                totalTokens: usage.totalTokens,
-                requestLimit,
-                tokenLimit,
-            },
-            subscription: subscription
-                ? {
-                    id: subscription.id,
-                    planId: subscription.planId,
-                    status: subscription.status,
-                    currentPeriodStart: subscription.currentPeriodStart,
-                    currentPeriodEnd: subscription.currentPeriodEnd,
-                    cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
-                }
-                : null,
-        };
-    }
-    // ─── Cancel ────────────────────────────────────────────────────────────
-    async cancelSubscription(tenantId, immediately = false) {
-        const subscription = await this.subscriptions.findActiveForTenant(tenantId);
-        if (!subscription?.providerSubscriptionId) {
-            throw new TenantBillingError('no_active_subscription', 'No active subscription found');
-        }
-        await this.adapter.cancelSubscription(subscription.providerSubscriptionId, !immediately);
-        await this.subscriptions.update(subscription.id, {
-            cancelAtPeriodEnd: !immediately,
-            status: immediately ? 'canceled' : subscription.status,
-        });
-        if (immediately) {
-            await this.tenants.update(tenantId, { planId: await this.getDefaultPlanId() });
-        }
-    }
-    // ─── Webhook (called by the public webhook handler) ────────────────────
-    /**
-     * Handle a webhook event whose `data.metadata.tenantId` indicates a tenant
-     * subscription. Returns true if handled. The caller should fall through to
-     * the user-centric handler when this returns false.
-     */
-    async handleWebhookEvent(event) {
-        const data = event.data;
-        const tenantId = data.metadata?.tenantId;
-        if (!tenantId)
-            return false;
-        switch (event.type) {
-            case 'checkout.session.completed':
-                await this.onCheckoutCompleted(event.data, tenantId);
-                return true;
-            case 'customer.subscription.updated':
-                await this.onSubscriptionUpdated(event.data, tenantId);
-                return true;
-            case 'customer.subscription.deleted':
-                await this.onSubscriptionDeleted(event.data, tenantId);
-                return true;
-            case 'invoice.payment_failed':
-                await this.onPaymentFailed(event.data);
-                return true;
-            default:
-                return true; // unknown but tagged as tenant — swallow
-        }
-    }
-    async onCheckoutCompleted(data, tenantId) {
-        const { metadata, subscription: subscriptionId, customer } = data;
-        const planId = metadata?.planId;
-        if (!planId)
-            return;
-        let periodEnd = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
-        if (subscriptionId) {
-            const sub = await this.adapter.getSubscription(subscriptionId);
-            periodEnd = sub.currentPeriodEnd;
-        }
-        const existing = await this.subscriptions.findByTenantAndPlan(tenantId, planId);
-        if (existing) {
-            await this.subscriptions.update(existing.id, {
-                status: 'active',
-                providerSubscriptionId: subscriptionId,
-                providerCustomerId: customer,
-                currentPeriodEnd: periodEnd,
-                cancelAtPeriodEnd: false,
-            });
-        }
-        else {
-            await this.subscriptions.create({
-                tenantId,
-                planId,
-                status: 'active',
-                providerSubscriptionId: subscriptionId,
-                providerCustomerId: customer,
-                currentPeriodStart: new Date(),
-                currentPeriodEnd: periodEnd,
-                cancelAtPeriodEnd: false,
-            });
-        }
-        await this.tenants.update(tenantId, {
-            planId,
-            providerCustomerId: customer,
-        });
-        this.opts.logger?.log(`Tenant ${tenantId} activated plan "${planId}"`);
-    }
-    async onSubscriptionUpdated(data, _tenantId) {
-        const { id, status, current_period_end, cancel_at_period_end } = data;
-        const periodEnd = typeof current_period_end === 'number' && Number.isFinite(current_period_end)
-            ? new Date(current_period_end * 1000)
-            : undefined;
-        await this.subscriptions.updateByProviderId(id, {
-            status: status,
-            cancelAtPeriodEnd: cancel_at_period_end ?? false,
-            ...(periodEnd ? { currentPeriodEnd: periodEnd } : {}),
-        });
-    }
-    async onSubscriptionDeleted(data, tenantId) {
-        const { id } = data;
-        await this.subscriptions.updateByProviderId(id, { status: 'canceled' });
-        await this.tenants.update(tenantId, { planId: await this.getDefaultPlanId() });
-    }
-    async onPaymentFailed(data) {
-        const { subscription } = data;
-        if (subscription) {
-            await this.subscriptions.updateByProviderId(subscription, { status: 'past_due' });
-        }
-    }
-    // ─── Plan enforcement ──────────────────────────────────────────────────
-    /**
-     * Decide whether a tenant is still within its monthly quotas. Designed to be
-     * called on the hot path (every chat request) — does one aggregate query
-     * against `af_usage_records` and one tenant lookup.
-     *
-     * Limits of `-1` mean "unlimited" for that dimension (per plan definition
-     * convention). Returns `{ allowed: false, reason }` when any positive limit
-     * has been reached or exceeded.
-     */
-    async checkLimits(tenantId) {
-        const tenant = await this.tenants.findById(tenantId);
-        if (!tenant)
-            throw new TenantBillingError('not_found', 'Tenant not found');
-        const plan = await this.getPlan(tenant.planId);
-        const requestLimit = plan?.limits.requestsPerMonth
-            ?? this.opts.defaultLimits?.requestsPerMonth
-            ?? -1;
-        const tokenLimit = plan?.limits.tokensPerMonth
-            ?? this.opts.defaultLimits?.tokensPerMonth
-            ?? -1;
-        const period = currentBillingPeriod();
-        const summed = await this.usageRecords.sumForTenantPeriod(tenantId, period);
-        const reasons = [];
-        if (requestLimit > 0 && summed.requestCount >= requestLimit) {
-            reasons.push(`Monthly request limit reached (${requestLimit} requests)`);
-        }
-        if (tokenLimit > 0 && summed.totalTokens >= tokenLimit) {
-            reasons.push(`Monthly token limit reached (${tokenLimit} tokens)`);
-        }
-        return {
-            allowed: reasons.length === 0,
-            reason: reasons.length > 0 ? reasons.join('; ') : undefined,
-            usage: {
-                period,
-                requestCount: summed.requestCount,
-                totalTokens: summed.totalTokens,
-                requestLimit,
-                tokenLimit,
-            },
-        };
-    }
-    // ─── Usage aggregation ─────────────────────────────────────────────────
-    async aggregateTenantUsage(tenantId) {
-        return this.usageRecords.sumForTenantPeriod(tenantId, currentBillingPeriod());
-    }
-}
-exports.TenantBillingService = TenantBillingService;
-class TenantBillingError extends Error {
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.status = code === 'not_found' ? 404 : 400;
-    }
-}
-exports.TenantBillingError = TenantBillingError;
-function currentBillingPeriod() {
-    const d = new Date();
-    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
-}

package/dist/services/tenant.service.d.ts

@@ -1,54 +0,0 @@
-import type { TenantRepository, TenantListOptions, ExternalUserRepository, UserRepository } from '../repositories';
-import type { Tenant } from '../domain/tenant';
-import type { ExternalUser } from '../domain/external-user';
-export declare class TenantError extends Error {
-    status: number;
-    code: 'not_found' | 'forbidden';
-    constructor(code: 'not_found' | 'forbidden', message: string);
-}
-export declare class TenantService {
-    private readonly tenants;
-    private readonly externalUsers;
-    private readonly users;
-    constructor(tenants: TenantRepository, externalUsers: ExternalUserRepository, users: UserRepository);
-    create(input: {
-        name: string;
-        ownerUserId: string;
-        planId?: string;
-    }): Promise<Tenant>;
-    findById(id: string): Promise<Tenant | null>;
-    listForOwner(ownerUserId: string, opts?: TenantListOptions): Promise<{
-        items: Tenant[];
-        total: number;
-    }>;
-    /**
-     * List every tenant in the system. Controllers MUST gate this behind a
-     * platform-admin check before calling — the service intentionally doesn't,
-     * so it stays usable from contexts that have already authorized the call.
-     */
-    listAll(opts?: TenantListOptions): Promise<{
-        items: Tenant[];
-        total: number;
-    }>;
-    /**
-     * Throws if the user isn't the owner. Used by admin endpoints.
-     *
-     * Pass `allowAnyOwner: true` to skip the owner check — controllers should
-     * set this when the caller is a platform admin, so super-admins can manage
-     * any tenant. The not-found path still fires when the tenantId is bogus.
-     */
-    assertOwner(tenantId: string, userId: string, opts?: {
-        allowAnyOwner?: boolean;
-    }): Promise<Tenant>;
-    /**
-     * Look up (tenantId, externalId) → internal User. Creates the linkage on
-     * first use. Also creates a placeholder User row so the rest of the system
-     * (conversations, usage, billing) can reference it.
-     */
-    ensureExternalUser(input: {
-        tenantId: string;
-        externalId: string;
-        email?: string;
-        name?: string;
-    }): Promise<ExternalUser>;
-}