@agentforge-io/core 0.2.0

package/dist/services/billing.service.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BillingError = exports.BillingService = void 0;
+/**
+ * Billing for the B2C path: the end user is the payer. Mirrors
+ * TenantBillingService, scoped to individual users.
+ */
+class BillingService {
+    constructor(users, subscriptions, usageRecords, adapter, usageService, opts) {
+        this.users = users;
+        this.subscriptions = subscriptions;
+        this.usageRecords = usageRecords;
+        this.adapter = adapter;
+        this.usageService = usageService;
+        this.opts = opts;
+    }
+    // ─── Plans ──────────────────────────────────────────────────────────────
+    async getPlans() {
+        return this.opts.plans.list();
+    }
+    async getPlan(planId) {
+        const plan = await this.opts.plans.getPlan(planId);
+        if (!plan)
+            throw new BillingError('plan_not_found', `Plan "${planId}" not found`);
+        return plan;
+    }
+    async getDefaultPlanId() {
+        return this.opts.plans.getDefaultId();
+    }
+    // ─── Checkout ───────────────────────────────────────────────────────────
+    async createCheckout(input) {
+        const user = await this.users.findById(input.userId);
+        if (!user)
+            throw new BillingError('not_found', `User "${input.userId}" not found`);
+        const plan = await this.getPlan(input.planId);
+        if (!plan.stripePriceId) {
+            throw new BillingError('plan_not_purchasable', `Plan "${input.planId}" has no stripePriceId`);
+        }
+        // Lazy-create the Stripe customer for the user.
+        let customerId = user.providerCustomerId;
+        if (!customerId) {
+            customerId = await this.adapter.createCustomer({
+                email: user.email,
+                name: user.name,
+                metadata: { userId: user.id },
+            });
+            await this.users.update(user.id, { providerCustomerId: customerId });
+        }
+        const appUrl = input.appUrl ?? this.opts.billing?.appUrl ?? 'http://localhost:3000';
+        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: input.userId,
+            planId: input.planId,
+            stripePriceId: plan.stripePriceId,
+            successUrl,
+            cancelUrl,
+        });
+        return {
+            sessionId: session.sessionId,
+            url: session.url,
+            planId: input.planId,
+            userId: input.userId,
+        };
+    }
+    // ─── Portal ─────────────────────────────────────────────────────────────
+    async getPortalUrl(userId, returnUrl) {
+        const user = await this.users.findById(userId);
+        if (!user?.providerCustomerId) {
+            throw new BillingError('no_customer', 'User does not have a billing account');
+        }
+        const portalReturn = returnUrl ??
+            this.opts.billing?.portalReturnUrl ??
+            `${this.opts.billing?.appUrl ?? 'http://localhost:3000'}/billing`;
+        const url = await this.adapter.getPortalUrl(user.providerCustomerId, portalReturn);
+        return { url };
+    }
+    // ─── Webhook ────────────────────────────────────────────────────────────
+    async handleWebhook(payload, signature) {
+        const event = await this.adapter.handleWebhook(payload, signature);
+        this.opts.logger?.log(`Processing webhook event: ${event.type}`);
+        switch (event.type) {
+            case 'checkout.session.completed':
+                await this.onCheckoutCompleted(event.data);
+                break;
+            case 'customer.subscription.updated':
+                await this.onSubscriptionUpdated(event.data);
+                break;
+            case 'customer.subscription.deleted':
+                await this.onSubscriptionDeleted(event.data);
+                break;
+            case 'invoice.payment_failed':
+                await this.onPaymentFailed(event.data);
+                break;
+            default:
+                this.opts.logger?.debug?.(`Unhandled webhook event: ${event.type}`);
+        }
+    }
+    /**
+     * Same as handleWebhook but accepts an already-verified event. Used by
+     * routers that want to dispatch a single event to both the tenant and the
+     * user-centric handlers without re-verifying the signature.
+     */
+    async handleWebhookEvent(event) {
+        switch (event.type) {
+            case 'checkout.session.completed':
+                await this.onCheckoutCompleted(event.data);
+                break;
+            case 'customer.subscription.updated':
+                await this.onSubscriptionUpdated(event.data);
+                break;
+            case 'customer.subscription.deleted':
+                await this.onSubscriptionDeleted(event.data);
+                break;
+            case 'invoice.payment_failed':
+                await this.onPaymentFailed(event.data);
+                break;
+            default:
+                this.opts.logger?.debug?.(`Unhandled webhook event: ${event.type}`);
+        }
+    }
+    async onCheckoutCompleted(data) {
+        const { metadata, subscription: subscriptionId, customer } = data;
+        if (!metadata?.userId || !metadata?.planId)
+            return;
+        const plan = await this.opts.plans.getPlan(metadata.planId);
+        if (!plan)
+            return;
+        // 30 days default; refined when we can query the provider.
+        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.findByUserAndPlan(metadata.userId, metadata.planId);
+        if (existing) {
+            await this.subscriptions.update(existing.id, {
+                status: 'active',
+                providerSubscriptionId: subscriptionId,
+                providerCustomerId: customer,
+                currentPeriodEnd: periodEnd,
+                cancelAtPeriodEnd: false,
+            });
+        }
+        else {
+            await this.subscriptions.create({
+                userId: metadata.userId,
+                planId: metadata.planId,
+                status: 'active',
+                providerSubscriptionId: subscriptionId,
+                providerCustomerId: customer,
+                currentPeriodStart: new Date(),
+                currentPeriodEnd: periodEnd,
+                cancelAtPeriodEnd: false,
+            });
+        }
+        await this.users.update(metadata.userId, {
+            currentPlanId: metadata.planId,
+            providerCustomerId: customer,
+        });
+        this.opts.logger?.log(`User ${metadata.userId} activated plan "${metadata.planId}"`);
+    }
+    async onSubscriptionUpdated(data) {
+        const { id, status, current_period_end, cancel_at_period_end, metadata, items } = data;
+        if (!metadata?.userId)
+            return;
+        const periodEndTs = current_period_end ?? items?.data?.[0]?.current_period_end;
+        const periodEnd = typeof periodEndTs === 'number' && Number.isFinite(periodEndTs)
+            ? new Date(periodEndTs * 1000)
+            : undefined;
+        await this.subscriptions.updateByProviderId(id, {
+            status: status,
+            cancelAtPeriodEnd: cancel_at_period_end ?? false,
+            ...(periodEnd ? { currentPeriodEnd: periodEnd } : {}),
+        });
+    }
+    async onSubscriptionDeleted(data) {
+        const { id, metadata } = data;
+        await this.subscriptions.updateByProviderId(id, { status: 'canceled' });
+        if (metadata?.userId) {
+            const defaultPlanId = await this.getDefaultPlanId();
+            await this.users.update(metadata.userId, { currentPlanId: defaultPlanId });
+        }
+    }
+    async onPaymentFailed(data) {
+        const { subscription } = data;
+        if (subscription) {
+            await this.subscriptions.updateByProviderId(subscription, { status: 'past_due' });
+        }
+    }
+    // ─── Overview ───────────────────────────────────────────────────────────
+    async getOverview(userId) {
+        const user = await this.users.findById(userId);
+        const subscription = await this.subscriptions.findActiveForUser(userId);
+        const usage = await this.usageService.getSummary(userId);
+        const planId = user?.currentPlanId ?? (await this.getDefaultPlanId());
+        const plan = await this.opts.plans.getPlan(planId);
+        return {
+            subscription: subscription
+                ? {
+                    id: subscription.id,
+                    userId,
+                    planId: subscription.planId,
+                    status: subscription.status,
+                    providerSubscriptionId: subscription.providerSubscriptionId,
+                    providerCustomerId: subscription.providerCustomerId,
+                    currentPeriodStart: subscription.currentPeriodStart ?? new Date(),
+                    currentPeriodEnd: subscription.currentPeriodEnd ?? new Date(),
+                    trialEnd: subscription.trialEnd,
+                    cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
+                    createdAt: subscription.createdAt,
+                    updatedAt: subscription.updatedAt,
+                }
+                : null,
+            usage,
+            plan: {
+                id: planId,
+                name: plan?.name ?? planId,
+                features: plan?.features ?? [],
+                limits: {
+                    requestsPerMonth: plan?.limits.requestsPerMonth ?? -1,
+                    tokensPerMonth: plan?.limits.tokensPerMonth ?? -1,
+                },
+            },
+        };
+    }
+    // ─── Cancel ─────────────────────────────────────────────────────────────
+    async cancelSubscription(userId, immediately = false) {
+        const subscription = await this.subscriptions.findActiveForUser(userId);
+        if (!subscription?.providerSubscriptionId) {
+            throw new BillingError('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) {
+            const defaultPlanId = await this.getDefaultPlanId();
+            await this.users.update(userId, { currentPlanId: defaultPlanId });
+        }
+    }
+}
+exports.BillingService = BillingService;
+class BillingError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.status = code === 'not_found' ? 404 : 400;
+    }
+}
+exports.BillingError = BillingError;

package/dist/services/chat-token.service.d.ts

@@ -0,0 +1,29 @@
+import type { ChatToken, ChatTokenPatch } from '../domain/chat-token';
+import type { ChatTokenRepository } from '../repositories';
+export declare class ChatTokenError extends Error {
+    status: number;
+    code: 'not_found' | 'invalid' | 'origin_not_allowed' | 'revoked';
+    constructor(code: ChatTokenError['code'], message: string);
+}
+export interface CreateChatTokenInput {
+    tenantId: string;
+    agentId: string;
+    name: string;
+    allowedOrigins?: string[];
+    createdByUserId?: string;
+}
+export declare class ChatTokenService {
+    private readonly repo;
+    constructor(repo: ChatTokenRepository);
+    create(input: CreateChatTokenInput): Promise<ChatToken>;
+    listForAgent(tenantId: string, agentId: string): Promise<ChatToken[]>;
+    deactivate(token: string): Promise<void>;
+    update(token: string, patch: ChatTokenPatch): Promise<void>;
+    /**
+     * Public-path entry point. Returns the resolved token row, or throws with
+     * a code the HTTP layer maps to 403/404. Also pings `last_used_at` so the
+     * admin UI can show which tokens are actually live traffic.
+     */
+    authorize(rawToken: string, origin: string | undefined): Promise<ChatToken>;
+    private generateToken;
+}

package/dist/services/chat-token.service.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatTokenService = exports.ChatTokenError = void 0;
+const crypto_1 = require("crypto");
+class ChatTokenError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.status =
+            code === 'not_found' ? 404 : code === 'origin_not_allowed' ? 403 : code === 'revoked' ? 403 : 400;
+    }
+}
+exports.ChatTokenError = ChatTokenError;
+/** Public token prefix to make stolen ones easy to spot in logs. 32 hex
+ *  bytes ≈ 128 bits of entropy — plenty for a public-but-rotatable secret. */
+const TOKEN_PREFIX = 'aft_';
+const TOKEN_BYTES = 32;
+class ChatTokenService {
+    constructor(repo) {
+        this.repo = repo;
+    }
+    async create(input) {
+        if (!input.tenantId)
+            throw new ChatTokenError('invalid', 'tenantId is required');
+        if (!input.agentId)
+            throw new ChatTokenError('invalid', 'agentId is required');
+        if (!input.name?.trim())
+            throw new ChatTokenError('invalid', 'name is required');
+        const origins = (input.allowedOrigins ?? [])
+            .map((o) => o.trim())
+            .filter(Boolean);
+        for (const o of origins) {
+            if (/\s/.test(o)) {
+                throw new ChatTokenError('invalid', `Invalid origin: "${o}"`);
+            }
+        }
+        const record = {
+            token: this.generateToken(),
+            tenantId: input.tenantId,
+            agentId: input.agentId,
+            name: input.name.trim(),
+            allowedOrigins: origins.length > 0 ? origins : undefined,
+            isActive: true,
+            createdByUserId: input.createdByUserId,
+        };
+        return this.repo.create(record);
+    }
+    async listForAgent(tenantId, agentId) {
+        return this.repo.listForAgent(tenantId, agentId);
+    }
+    async deactivate(token) {
+        await this.repo.deactivate(token);
+    }
+    async update(token, patch) {
+        await this.repo.update(token, patch);
+    }
+    /**
+     * Public-path entry point. Returns the resolved token row, or throws with
+     * a code the HTTP layer maps to 403/404. Also pings `last_used_at` so the
+     * admin UI can show which tokens are actually live traffic.
+     */
+    async authorize(rawToken, origin) {
+        if (!rawToken)
+            throw new ChatTokenError('not_found', 'Missing chat token');
+        const row = await this.repo.findByToken(rawToken);
+        if (!row)
+            throw new ChatTokenError('not_found', 'Chat token not found');
+        if (!row.isActive)
+            throw new ChatTokenError('revoked', 'Chat token has been revoked');
+        if (row.allowedOrigins && row.allowedOrigins.length > 0) {
+            if (!origin) {
+                throw new ChatTokenError('origin_not_allowed', 'This widget can only be used from an allowed origin (Origin header missing).');
+            }
+            if (!matchesAllowedOrigin(origin, row.allowedOrigins)) {
+                throw new ChatTokenError('origin_not_allowed', `Origin "${origin}" is not allowed for this widget.`);
+            }
+        }
+        // Fire-and-forget: don't make the request wait on this write.
+        this.repo.touch(rawToken).catch(() => { });
+        return row;
+    }
+    generateToken() {
+        return `${TOKEN_PREFIX}${(0, crypto_1.randomBytes)(TOKEN_BYTES).toString('hex')}`;
+    }
+}
+exports.ChatTokenService = ChatTokenService;
+/**
+ * Origin matching: each allowed entry can be either a full origin
+ * ("https://acme.com") or just a host ("acme.com"). Exact match only — no
+ * wildcards on purpose.
+ */
+function matchesAllowedOrigin(origin, allowed) {
+    const reqHost = hostnameOf(origin);
+    if (!reqHost)
+        return false;
+    for (const entry of allowed) {
+        const allowedHost = hostnameOf(entry) ?? entry.toLowerCase();
+        if (allowedHost === reqHost)
+            return true;
+    }
+    return false;
+}
+function hostnameOf(value) {
+    try {
+        return new URL(value).hostname.toLowerCase();
+    }
+    catch {
+        // Bare hostname like "acme.com" — URL ctor rejects it without scheme.
+        if (/^[a-z0-9.-]+$/i.test(value))
+            return value.toLowerCase();
+        return null;
+    }
+}

package/dist/services/connector-registry.service.d.ts

@@ -0,0 +1,156 @@
+import type { ConnectorDefinition } from '../domain';
+import type { ConnectorAuthRepository } from '../repositories';
+import type { OAuth2Service } from './oauth2.service';
+import type { ToolRegistryService } from './tool-registry.service';
+import type { AgentToolDefinition } from '../types';
+export declare class ConnectorError extends Error {
+    status: number;
+    code: 'unknown_connector' | 'not_connected' | 'not_configured' | 'invalid_state' | 'token_exchange_failed';
+    constructor(code: ConnectorError['code'], message: string);
+}
+/**
+ * Host-supplied symmetric cipher for encrypting OAuth tokens at rest.
+ * Implemented in the platform's SecretsModule (AES-256-GCM with MASTER_KEY).
+ * Kept as an interface so @agentforge-io/core stays infrastructure-agnostic.
+ */
+export interface TokenCipher {
+    encrypt(plaintext: string): Buffer;
+    decrypt(blob: Buffer): string;
+}
+/**
+ * Transient state stashed between `startAuthorize` and the OAuth callback.
+ * Persisted in the store so the callback (which arrives as a separate HTTP
+ * request) can pick up the connector id and the user it's for.
+ */
+export interface AuthorizeState {
+    userId: string;
+    connectorId: string;
+    pkceVerifier?: string;
+    createdAt: number;
+}
+/**
+ * Pluggable storage for the short-lived state map. Defaults to an
+ * in-memory implementation; production deployments behind multiple
+ * server instances should plug in a Redis-backed store.
+ */
+export interface AuthorizeStateStore {
+    set(state: string, value: AuthorizeState): Promise<void> | void;
+    consume(state: string): Promise<AuthorizeState | null> | AuthorizeState | null;
+}
+export declare class InMemoryAuthorizeStateStore implements AuthorizeStateStore {
+    private readonly map;
+    set(state: string, value: AuthorizeState): void;
+    consume(state: string): AuthorizeState | null;
+}
+export interface ConnectorStatus {
+    connectorId: string;
+    name: string;
+    description: string;
+    category?: string;
+    iconUrl?: string;
+    /** `true` when the operator has supplied client creds for this provider.
+     *  When `false`, the user cannot click Connect — the card shows a "Needs
+     *  admin setup" hint instead. Kept distinct from `connected` so the
+     *  Directory can render the full catalog even on a freshly-installed
+     *  platform. */
+    configured: boolean;
+    connected: boolean;
+    accountLabel?: string;
+    connectedAt?: Date;
+}
+interface ConnectorRegistryDeps {
+    oauth: OAuth2Service;
+    authRepo: ConnectorAuthRepository;
+    cipher: TokenCipher;
+    toolRegistry: ToolRegistryService;
+    stateStore?: AuthorizeStateStore;
+    /** Refresh access tokens this many seconds before they expire so a
+     *  tool call started right at the edge doesn't 401 mid-flight. */
+    refreshSkewSeconds?: number;
+}
+/**
+ * Central registry for OAuth-based connectors. Holds the in-memory map of
+ * `ConnectorDefinition`s, drives the OAuth dance via `OAuth2Service`,
+ * encrypts/persists tokens via `cipher` + `authRepo`, and on each agent
+ * run synthesises per-user tool definitions whose handlers receive a
+ * fresh access token.
+ *
+ * The lifecycle is intentionally not "register tools globally at boot" —
+ * doing so would leak one user's tools to another. Instead, callers ask
+ * the registry for `toolsForUser(userId)` and merge the result into the
+ * ToolRegistry's per-call view.
+ */
+export declare class ConnectorRegistryService {
+    private readonly deps;
+    private readonly defs;
+    /**
+     * Connectors whose client creds are present. The registry treats the
+     * "catalog" (which providers we *support*) as separate from the
+     * "configured" set (which ones can actually run an OAuth flow). Hosts
+     * call `setConfigured(id, def)` when secrets land and `markUnconfigured`
+     * when they're cleared — neither call removes the definition from the
+     * catalog, so the Directory always shows the full grid.
+     */
+    private readonly configured;
+    private readonly stateStore;
+    private readonly refreshSkewSeconds;
+    constructor(deps: ConnectorRegistryDeps);
+    /**
+     * Register a connector into the catalog. Catalog registration is one-shot
+     * (per-id) and unrelated to credential availability — call this at boot
+     * for every provider the platform supports. To then mark it as ready for
+     * OAuth flows, follow up with `setConfigured()` once creds resolve.
+     */
+    register(def: ConnectorDefinition): void;
+    /**
+     * Mark a registered connector as configured AND refresh its definition.
+     * The definition is replaced because OAuth `clientId` / `clientSecret`
+     * live inside it — when the operator rotates creds the def itself
+     * changes. Existing per-user `ConnectorAuth` rows keep working: tokens
+     * are provider-issued, not tied to the client secret.
+     */
+    setConfigured(def: ConnectorDefinition): void;
+    /**
+     * Mark a connector as unconfigured. The definition stays in the catalog
+     * (so the card keeps rendering with a "Needs admin setup" hint) but
+     * `startAuthorize` will refuse and per-user tools stop surfacing — we
+     * can't refresh tokens without client creds either, so silently dropping
+     * tools is friendlier than letting them 401 mid-call.
+     */
+    markUnconfigured(connectorId: string): boolean;
+    /**
+     * Hard-remove a connector from the catalog. Rarely needed — used by
+     * tests or to retire a deprecated provider. Per-user rows are NOT
+     * deleted automatically; the caller is responsible for that cleanup.
+     */
+    unregister(connectorId: string): boolean;
+    isConfigured(connectorId: string): boolean;
+    list(): ConnectorDefinition[];
+    get(connectorId: string): ConnectorDefinition;
+    startAuthorize(connectorId: string, userId: string, redirectUri: string): Promise<{
+        url: string;
+    }>;
+    /**
+     * Complete the OAuth callback. Verifies the `state`, exchanges the code
+     * for tokens, encrypts them, and upserts the `ConnectorAuth` row.
+     *
+     * Returns the resolved connector id so the caller can redirect the user
+     * back to the directory page with confirmation.
+     */
+    completeAuthorize(state: string, code: string, redirectUri: string): Promise<{
+        connectorId: string;
+        userId: string;
+    }>;
+    listForUser(userId: string): Promise<ConnectorStatus[]>;
+    disconnect(userId: string, connectorId: string): Promise<void>;
+    /**
+     * Returns the toolbelt for `userId`: one `AgentToolDefinition` per tool
+     * of every connector the user has authorized. Each handler is bound to a
+     * `ConnectorToolContext` whose `getAccessToken` lazy-refreshes when the
+     * cached token is close to expiry.
+     */
+    toolsForUser(userId: string): Promise<AgentToolDefinition[]>;
+    private upsertAuth;
+    private getAccessToken;
+}
+export {};