mcpmake 0.1.0

package/dist/analyzer/site-crawler.js

@@ -0,0 +1,235 @@
+/**
+ * Crawls a website using Playwright, visiting pages breadth-first
+ * and extracting interactive elements from each page.
+ */
+import { chromium } from 'playwright';
+import { parsePage } from './dom-parser.js';
+import { captureViewportScreenshot } from './screenshot-capture.js';
+import { logger } from '../utils/logger.js';
+import crypto from 'node:crypto';
+const DEFAULT_DEPTH = 2;
+const DEFAULT_MAX_PAGES = 20;
+const DEFAULT_TIMEOUT = 5 * 60 * 1000;
+const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+/**
+ * Crawl a website and return a SiteDescriptor with all discovered pages.
+ */
+export async function crawlSite(options) {
+    const depth = options.depth ?? DEFAULT_DEPTH;
+    const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const viewport = options.viewport ?? DEFAULT_VIEWPORT;
+    const captureScreenshots = options.captureScreenshots ?? true;
+    const parsedUrl = new URL(options.url);
+    if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
+        throw new Error('Only http/https URLs are supported');
+    }
+    const baseUrl = `${parsedUrl.protocol}//${parsedUrl.host}`;
+    const captureHar = options.captureHar ?? false;
+    const pages = [];
+    const screenshots = new Map();
+    const harEntries = [];
+    const pendingRequests = new Map();
+    const visited = new Set();
+    const queue = [
+        { url: options.url, currentDepth: 0 },
+    ];
+    let browser;
+    try {
+        browser = await chromium.launch({ headless: options.headless ?? false });
+        const context = await browser.newContext({ viewport });
+        const page = await context.newPage();
+        // Optionally capture network requests as HAR entries during crawl
+        if (captureHar) {
+            page.on('request', (request) => {
+                pendingRequests.set(request, { startTime: Date.now() });
+            });
+            page.on('response', async (response) => {
+                const request = response.request();
+                const pending = pendingRequests.get(request);
+                if (!pending)
+                    return;
+                pendingRequests.delete(request);
+                try {
+                    const entry = await buildCrawlHarEntry(request, response, pending.startTime);
+                    harEntries.push(entry);
+                }
+                catch {
+                    // Some responses can't be read (redirects, aborted)
+                }
+            });
+        }
+        logger.info(`Crawling site: ${options.url} (depth: ${depth}, max pages: ${maxPages})`);
+        let lastActivityTime = Date.now();
+        while (queue.length > 0 && pages.length < maxPages) {
+            const item = queue.shift();
+            const normalizedUrl = normalizeUrl(item.url);
+            // Skip if already visited or different origin
+            if (visited.has(normalizedUrl))
+                continue;
+            if (!item.url.startsWith(baseUrl))
+                continue;
+            visited.add(normalizedUrl);
+            // Check idle timeout
+            if (Date.now() - lastActivityTime > timeout) {
+                logger.warn('Idle timeout reached during crawl');
+                break;
+            }
+            try {
+                logger.info(`[${pages.length + 1}/${maxPages}] Visiting: ${item.url}`);
+                await page.goto(item.url, {
+                    waitUntil: 'domcontentloaded',
+                    timeout: 15_000,
+                });
+                // Wait briefly for dynamic content to render
+                await page.waitForTimeout(1000);
+                lastActivityTime = Date.now();
+                // Parse the page DOM
+                const pageDescriptor = await parsePage(page);
+                pageDescriptor.url = item.url;
+                // Capture screenshot if enabled
+                if (captureScreenshots) {
+                    const screenshot = await captureViewportScreenshot(page);
+                    pageDescriptor.screenshotHash = screenshot.hash;
+                    screenshots.set(pageDescriptor.pageId, screenshot.data);
+                }
+                pages.push(pageDescriptor);
+                // Queue navigation links for further crawling
+                if (item.currentDepth < depth) {
+                    for (const link of pageDescriptor.links) {
+                        if (link.isNavigation && !visited.has(normalizeUrl(link.href))) {
+                            queue.push({ url: link.href, currentDepth: item.currentDepth + 1 });
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.warn(`Failed to crawl ${item.url}: ${err}`);
+            }
+        }
+        // Close browser
+        await browser.close().catch(() => { });
+        browser = undefined;
+    }
+    catch (error) {
+        if (browser)
+            await browser.close().catch(() => { });
+        throw error;
+    }
+    logger.info(`Crawl complete: ${pages.length} pages discovered`);
+    // Extract site metadata from the first page
+    const metadata = {
+        title: pages[0]?.title,
+        description: undefined,
+        favicon: undefined,
+    };
+    const siteDescriptor = {
+        siteId: generateSiteId(baseUrl),
+        baseUrl,
+        pages,
+        analyzedAt: new Date().toISOString(),
+        version: 1,
+        crawlDepth: depth,
+        metadata,
+    };
+    return {
+        siteDescriptor,
+        screenshots,
+        ...(captureHar ? { harEntries } : {}),
+    };
+}
+// ─── HAR Capture (for hybrid mode) ─────────────────────────────────
+const MAX_RESPONSE_BODY_BYTES = 5 * 1024 * 1024;
+const SKIP_BODY_MIME_TYPES = ['image/', 'video/', 'audio/', 'font/', 'application/octet-stream'];
+async function buildCrawlHarEntry(request, response, startTime) {
+    const elapsed = Date.now() - startTime;
+    const url = request.url();
+    const parsedUrl = new URL(url);
+    const requestHeaders = Object.entries(request.headers()).map(([name, value]) => ({
+        name,
+        value,
+    }));
+    const queryString = [...parsedUrl.searchParams.entries()].map(([name, value]) => ({
+        name,
+        value,
+    }));
+    const postData = request.postData();
+    const contentTypeHeader = request.headers()['content-type'] ?? '';
+    const responseHeaders = Object.entries(response.headers()).map(([name, value]) => ({
+        name,
+        value,
+    }));
+    let responseText;
+    const responseMimeType = response.headers()['content-type'] ?? '';
+    const skipBody = SKIP_BODY_MIME_TYPES.some((m) => responseMimeType.startsWith(m));
+    const contentLength = parseInt(response.headers()['content-length'] ?? '0', 10);
+    if (!skipBody && contentLength <= MAX_RESPONSE_BODY_BYTES) {
+        try {
+            const body = await response.body();
+            if (body.length <= MAX_RESPONSE_BODY_BYTES) {
+                responseText = body.toString('utf-8');
+            }
+        }
+        catch {
+            // Body may not be available
+        }
+    }
+    return {
+        startedDateTime: new Date(startTime).toISOString(),
+        time: elapsed,
+        request: {
+            method: request.method(),
+            url,
+            httpVersion: 'HTTP/1.1',
+            headers: requestHeaders,
+            queryString,
+            cookies: [],
+            headersSize: -1,
+            bodySize: postData ? Buffer.byteLength(postData) : 0,
+            ...(postData
+                ? {
+                    postData: {
+                        mimeType: contentTypeHeader.split(';')[0].trim() || 'application/octet-stream',
+                        text: postData,
+                    },
+                }
+                : {}),
+        },
+        response: {
+            status: response.status(),
+            statusText: response.statusText(),
+            httpVersion: 'HTTP/1.1',
+            headers: responseHeaders,
+            cookies: [],
+            content: {
+                size: responseText ? Buffer.byteLength(responseText) : 0,
+                mimeType: responseMimeType.split(';')[0].trim() || 'application/octet-stream',
+                ...(responseText ? { text: responseText } : {}),
+            },
+            redirectURL: '',
+            headersSize: -1,
+            bodySize: responseText ? Buffer.byteLength(responseText) : 0,
+        },
+        cache: {},
+        timings: {
+            send: 1,
+            wait: Math.max(1, elapsed - 2),
+            receive: 1,
+        },
+    };
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+function normalizeUrl(url) {
+    try {
+        const parsed = new URL(url);
+        // Remove trailing slash, fragment, and normalize
+        return `${parsed.origin}${parsed.pathname.replace(/\/$/, '')}${parsed.search}`;
+    }
+    catch {
+        return url;
+    }
+}
+function generateSiteId(baseUrl) {
+    const hash = crypto.createHash('sha256').update(baseUrl).digest('hex').slice(0, 12);
+    return `site_${hash}`;
+}

package/dist/cloud/billing/billing-engine.d.ts

@@ -0,0 +1,44 @@
+export type BillingPlan = 'free' | 'hobbyist' | 'pro' | 'team' | 'enterprise';
+export interface PlanLimits {
+    /** Maximum allowed usage in minutes per billing period */
+    maxMinutes: number;
+    plan: BillingPlan;
+}
+export interface QuotaCheckResult {
+    allowed: boolean;
+    /** Minutes remaining in the current period */
+    remaining: number;
+    /** Plan limit in minutes */
+    limit: number;
+}
+/** Get the minute limits for a given billing plan. */
+export declare function getPlanLimits(plan: BillingPlan): PlanLimits;
+/** Monthly tool-call limit for a plan. */
+export declare function getCallLimit(plan: BillingPlan): number;
+/** Maximum hosted servers for a plan. */
+export declare function getServerLimit(plan: BillingPlan): number;
+/**
+ * Check whether a user may create another server given how many they already
+ * have. `allowed` is false once the count reaches the plan's server limit.
+ */
+export declare function checkServerLimit(plan: BillingPlan, currentCount: number): {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+};
+/**
+ * Check whether a user has tool-call quota remaining for the billing period.
+ */
+export declare function checkCallQuota(plan: BillingPlan, usedCalls: number): {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+};
+/**
+ * Check whether a user has quota remaining under their plan.
+ *
+ * @param _userId - The user ID (reserved for future per-user overrides)
+ * @param plan - The user's billing plan
+ * @param currentUsageMs - Current usage in milliseconds for the billing period
+ */
+export declare function checkQuota(_userId: string, plan: BillingPlan, currentUsageMs: number): QuotaCheckResult;

package/dist/cloud/billing/billing-engine.js

@@ -0,0 +1,81 @@
+const PLAN_LIMITS = {
+    free: 500,
+    hobbyist: 5_000,
+    pro: 50_000,
+    team: 500_000,
+    enterprise: Infinity,
+};
+/**
+ * Monthly tool-call (request) limits per plan. Overage on paid plans is billed
+ * separately; the free tier is a hard cap. Tunable business constants.
+ */
+const PLAN_CALL_LIMITS = {
+    free: 1_000,
+    hobbyist: 10_000,
+    pro: 100_000,
+    team: 1_000_000,
+    enterprise: Infinity,
+};
+/** Maximum number of concurrently hosted servers per plan. */
+const PLAN_SERVER_LIMITS = {
+    free: 1,
+    hobbyist: 3,
+    pro: 5,
+    team: 20,
+    enterprise: Infinity,
+};
+/** Get the minute limits for a given billing plan. */
+export function getPlanLimits(plan) {
+    return {
+        maxMinutes: PLAN_LIMITS[plan],
+        plan,
+    };
+}
+/** Monthly tool-call limit for a plan. */
+export function getCallLimit(plan) {
+    return PLAN_CALL_LIMITS[plan] ?? PLAN_CALL_LIMITS.free;
+}
+/** Maximum hosted servers for a plan. */
+export function getServerLimit(plan) {
+    return PLAN_SERVER_LIMITS[plan] ?? PLAN_SERVER_LIMITS.free;
+}
+/**
+ * Check whether a user may create another server given how many they already
+ * have. `allowed` is false once the count reaches the plan's server limit.
+ */
+export function checkServerLimit(plan, currentCount) {
+    const limit = getServerLimit(plan);
+    return {
+        allowed: currentCount < limit,
+        limit,
+        remaining: Math.max(0, limit - currentCount),
+    };
+}
+/**
+ * Check whether a user has tool-call quota remaining for the billing period.
+ */
+export function checkCallQuota(plan, usedCalls) {
+    const limit = getCallLimit(plan);
+    return {
+        allowed: usedCalls < limit,
+        limit,
+        remaining: Math.max(0, limit - usedCalls),
+    };
+}
+/**
+ * Check whether a user has quota remaining under their plan.
+ *
+ * @param _userId - The user ID (reserved for future per-user overrides)
+ * @param plan - The user's billing plan
+ * @param currentUsageMs - Current usage in milliseconds for the billing period
+ */
+export function checkQuota(_userId, plan, currentUsageMs) {
+    const limit = PLAN_LIMITS[plan];
+    const usedMinutes = currentUsageMs / 60_000;
+    const remaining = Math.max(0, limit - usedMinutes);
+    return {
+        allowed: usedMinutes < limit,
+        remaining,
+        limit,
+    };
+}

package/dist/cloud/billing/credit-store.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Promotional tool-call credits.
+ *
+ * A persistent per-user balance of bonus tool-calls, consumed when a user is
+ * over their plan's monthly call quota (before the 429 hard cap). Admins grant
+ * and revoke from the dashboard; the serving hot path consumes.
+ *
+ * Concurrency: `consume` MUST be atomic — two concurrent over-quota requests
+ * must not both decrement from the same read value (lost update = leaked free
+ * credits). The Pg implementation does the decrement in a single conditional
+ * UPDATE; the in-memory one is safe because each call runs to completion within
+ * one event-loop turn.
+ *
+ * The ledger records only admin grants/revokes (low volume, truly auditable).
+ * Per-request consumption is intentionally NOT ledgered — that would add a write
+ * per over-quota tool call on the hot path; consumption totals are derivable
+ * from usage accounting.
+ */
+import type { Database } from '../db/index.js';
+export interface ConsumeResult {
+    consumed: boolean;
+    /** Remaining balance after the operation (best-effort; 0 when not consumed). */
+    balance: number;
+}
+export interface LedgerEntry {
+    delta: number;
+    reason: string;
+    actorId: string | null;
+    balanceAfter: number | null;
+    createdAt: string;
+}
+export interface CreditStore {
+    balance(userId: string): Promise<number>;
+    /** Add `amount` credits. Returns the new balance. */
+    grant(userId: string, amount: number, actorId: string): Promise<number>;
+    /** Remove up to `amount` credits (never below zero). Returns the new balance. */
+    revoke(userId: string, amount: number, actorId: string): Promise<number>;
+    /** Atomically consume `amount` credits if the balance covers it (all-or-nothing). */
+    consume(userId: string, amount: number): Promise<ConsumeResult>;
+    recentLedger(userId: string, limit: number): Promise<LedgerEntry[]>;
+}
+export declare class InMemoryCreditStore implements CreditStore {
+    private balances;
+    private ledger;
+    /** Set a balance, bounding the map so a long-lived dev process can't grow it
+     * without limit (drops the oldest-inserted half when the cap is exceeded). */
+    private setBalance;
+    private push;
+    balance(userId: string): Promise<number>;
+    grant(userId: string, amount: number, actorId: string): Promise<number>;
+    revoke(userId: string, amount: number, actorId: string): Promise<number>;
+    consume(userId: string, amount: number): Promise<ConsumeResult>;
+    recentLedger(userId: string, limit: number): Promise<LedgerEntry[]>;
+}
+export declare class PgCreditStore implements CreditStore {
+    private db;
+    constructor(db: Database);
+    private writeLedger;
+    balance(userId: string): Promise<number>;
+    grant(userId: string, amount: number, actorId: string): Promise<number>;
+    revoke(userId: string, amount: number, actorId: string): Promise<number>;
+    consume(userId: string, amount: number): Promise<ConsumeResult>;
+    recentLedger(userId: string, limit: number): Promise<LedgerEntry[]>;
+}

package/dist/cloud/billing/credit-store.js

@@ -0,0 +1,168 @@
+/**
+ * Promotional tool-call credits.
+ *
+ * A persistent per-user balance of bonus tool-calls, consumed when a user is
+ * over their plan's monthly call quota (before the 429 hard cap). Admins grant
+ * and revoke from the dashboard; the serving hot path consumes.
+ *
+ * Concurrency: `consume` MUST be atomic — two concurrent over-quota requests
+ * must not both decrement from the same read value (lost update = leaked free
+ * credits). The Pg implementation does the decrement in a single conditional
+ * UPDATE; the in-memory one is safe because each call runs to completion within
+ * one event-loop turn.
+ *
+ * The ledger records only admin grants/revokes (low volume, truly auditable).
+ * Per-request consumption is intentionally NOT ledgered — that would add a write
+ * per over-quota tool call on the hot path; consumption totals are derivable
+ * from usage accounting.
+ */
+import { randomBytes } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// In-memory (dev / no database)
+// ---------------------------------------------------------------------------
+const MAX_INMEMORY_LEDGER = 5_000;
+/** Bound the per-user balance map (dev/no-DB only; prod uses the users table). */
+const MAX_INMEMORY_BALANCES = 50_000;
+export class InMemoryCreditStore {
+    balances = new Map();
+    ledger = [];
+    /** Set a balance, bounding the map so a long-lived dev process can't grow it
+     * without limit (drops the oldest-inserted half when the cap is exceeded). */
+    setBalance(userId, value) {
+        if (!this.balances.has(userId) && this.balances.size >= MAX_INMEMORY_BALANCES) {
+            const keep = Math.floor(MAX_INMEMORY_BALANCES / 2);
+            this.balances = new Map([...this.balances].slice(-keep));
+        }
+        this.balances.set(userId, value);
+    }
+    push(entry) {
+        this.ledger.push(entry);
+        if (this.ledger.length > MAX_INMEMORY_LEDGER) {
+            this.ledger.splice(0, this.ledger.length - MAX_INMEMORY_LEDGER);
+        }
+    }
+    async balance(userId) {
+        return this.balances.get(userId) ?? 0;
+    }
+    async grant(userId, amount, actorId) {
+        const next = (this.balances.get(userId) ?? 0) + amount;
+        this.setBalance(userId, next);
+        this.push({
+            userId,
+            delta: amount,
+            reason: 'admin_grant',
+            actorId,
+            balanceAfter: next,
+            createdAt: new Date().toISOString(),
+        });
+        return next;
+    }
+    async revoke(userId, amount, actorId) {
+        const current = this.balances.get(userId) ?? 0;
+        const next = Math.max(0, current - amount);
+        this.setBalance(userId, next);
+        this.push({
+            userId,
+            delta: next - current,
+            reason: 'admin_revoke',
+            actorId,
+            balanceAfter: next,
+            createdAt: new Date().toISOString(),
+        });
+        return next;
+    }
+    async consume(userId, amount) {
+        const current = this.balances.get(userId) ?? 0;
+        if (amount <= 0 || current < amount)
+            return { consumed: false, balance: 0 };
+        const next = current - amount;
+        this.setBalance(userId, next);
+        return { consumed: true, balance: next };
+    }
+    async recentLedger(userId, limit) {
+        return this.ledger
+            .filter((e) => e.userId === userId)
+            .slice(-limit)
+            .reverse()
+            .map(({ userId: _u, ...rest }) => rest);
+    }
+}
+// ---------------------------------------------------------------------------
+// Postgres
+// ---------------------------------------------------------------------------
+export class PgCreditStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async writeLedger(userId, delta, reason, actorId, balanceAfter) {
+        await this.db.query(`INSERT INTO credit_ledger (id, user_id, delta, reason, actor_id, balance_after)
+       VALUES ($1, $2, $3, $4, $5, $6)`, [randomBytes(16).toString('hex'), userId, delta, reason, actorId, balanceAfter]);
+    }
+    async balance(userId) {
+        const { rows } = await this.db.query('SELECT credits_calls FROM users WHERE id = $1', [userId]);
+        const v = rows[0]?.credits_calls ?? 0;
+        return typeof v === 'number' ? v : Number(v) || 0;
+    }
+    async grant(userId, amount, actorId) {
+        const { rows } = await this.db.query('UPDATE users SET credits_calls = credits_calls + $2 WHERE id = $1 RETURNING credits_calls', [userId, amount]);
+        if (rows.length === 0)
+            throw new Error(`User "${userId}" not found`);
+        const next = typeof rows[0].credits_calls === 'number'
+            ? rows[0].credits_calls
+            : Number(rows[0].credits_calls);
+        await this.writeLedger(userId, amount, 'admin_grant', actorId, next);
+        return next;
+    }
+    async revoke(userId, amount, actorId) {
+        // Single atomic statement: lock the row (FOR UPDATE), clamp at zero, and
+        // return both the old and new balance so the ledger delta is exact even
+        // under concurrent admin revokes (no read-modify-write window).
+        const { rows } = await this.db.query(`WITH prev AS (
+         SELECT credits_calls AS old_balance FROM users WHERE id = $1 FOR UPDATE
+       )
+       UPDATE users
+       SET credits_calls = GREATEST(0, users.credits_calls - $2)
+       FROM prev
+       WHERE users.id = $1
+       RETURNING users.credits_calls AS new_balance, prev.old_balance`, [userId, amount]);
+        if (rows.length === 0)
+            throw new Error(`User "${userId}" not found`);
+        const toNum = (v) => (typeof v === 'number' ? v : Number(v));
+        const next = toNum(rows[0].new_balance);
+        const before = toNum(rows[0].old_balance);
+        // Record the actual delta applied (clamped at zero), not the requested amount.
+        await this.writeLedger(userId, next - before, 'admin_revoke', actorId, next);
+        return next;
+    }
+    async consume(userId, amount) {
+        if (amount <= 0)
+            return { consumed: false, balance: 0 };
+        // Single atomic statement: decrement only if the balance covers it.
+        const { rows } = await this.db.query('UPDATE users SET credits_calls = credits_calls - $2 WHERE id = $1 AND credits_calls >= $2 RETURNING credits_calls', [userId, amount]);
+        if (rows.length === 0)
+            return { consumed: false, balance: 0 };
+        const balance = typeof rows[0].credits_calls === 'number'
+            ? rows[0].credits_calls
+            : Number(rows[0].credits_calls);
+        return { consumed: true, balance };
+    }
+    async recentLedger(userId, limit) {
+        const { rows } = await this.db.query(`SELECT delta, reason, actor_id, balance_after, created_at
+       FROM credit_ledger WHERE user_id = $1 ORDER BY created_at DESC LIMIT $2`, [userId, limit]);
+        return rows.map((row) => {
+            const createdAt = row.created_at;
+            return {
+                delta: typeof row.delta === 'number' ? row.delta : Number(row.delta ?? 0),
+                reason: String(row.reason ?? ''),
+                actorId: row.actor_id != null ? String(row.actor_id) : null,
+                balanceAfter: row.balance_after != null
+                    ? typeof row.balance_after === 'number'
+                        ? row.balance_after
+                        : Number(row.balance_after)
+                    : null,
+                createdAt: typeof createdAt === 'string' ? createdAt : new Date(createdAt).toISOString(),
+            };
+        });
+    }
+}

package/dist/cloud/billing/index.d.ts

@@ -0,0 +1,4 @@
+export { UsageTracker } from './usage-tracker.js';
+export type { UsageEvent, UsageEventType, UsageSummary } from './usage-tracker.js';
+export { checkQuota, getPlanLimits } from './billing-engine.js';
+export type { BillingPlan, PlanLimits, QuotaCheckResult } from './billing-engine.js';

package/dist/cloud/billing/index.js

@@ -0,0 +1,2 @@
+export { UsageTracker } from './usage-tracker.js';
+export { checkQuota, getPlanLimits } from './billing-engine.js';

package/dist/cloud/billing/usage-store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Durable per-user usage accounting tied to a billing period.
+ *
+ * Records tool calls (and total requests) for the served MCP traffic so that
+ * quota can be enforced and usage survives process restarts. Backed by the
+ * `usage_summaries` Postgres table when a database is configured; otherwise an
+ * in-memory fallback is used (dev / single-process).
+ */
+import type { Database } from '../db/index.js';
+export interface BillingPeriod {
+    /** ISO timestamp of the period start (inclusive). */
+    start: string;
+    /** ISO timestamp of the period end (exclusive). */
+    end: string;
+}
+/**
+ * Compute the billing period containing `now`.
+ *
+ * When `anchorEndMs` (a Stripe subscription's current_period_end) is provided
+ * and in the future, the period is the month ending at that anchor; otherwise
+ * it falls back to the calendar month (UTC). Calendar-month alignment is a safe
+ * default for the free tier and approximates monthly subscriptions closely.
+ */
+export declare function getBillingPeriod(now?: Date, anchorEndMs?: number): BillingPeriod;
+export interface UsageStore {
+    /** Add tool-call and request counts for a user in the given period. */
+    record(userId: string, period: BillingPeriod, toolCalls: number, requests: number): Promise<void>;
+    /** Total tool calls a user has made in the given period. */
+    getToolCalls(userId: string, period: BillingPeriod): Promise<number>;
+}
+export declare class InMemoryUsageStore implements UsageStore {
+    private counts;
+    private key;
+    record(userId: string, period: BillingPeriod, toolCalls: number, requests: number): Promise<void>;
+    getToolCalls(userId: string, period: BillingPeriod): Promise<number>;
+}
+export declare class PgUsageStore implements UsageStore {
+    private db;
+    constructor(db: Database);
+    record(userId: string, period: BillingPeriod, toolCalls: number, requests: number): Promise<void>;
+    getToolCalls(userId: string, period: BillingPeriod): Promise<number>;
+}