@muxoai/platform 1.2.3 → 1.3.0

package/dist/providers/stripe-billing.js

@@ -1,4 +1,85 @@
 import crypto from "node:crypto";
+const BILLING_TOOLS = [
+    {
+        slug: "billing.credits.topup",
+        upstreamSlug: "STRIPE_BILLING_CREDITS_TOPUP",
+        name: "Top Up Workspace Credits Wallet",
+        description: "Instantly add Instant & Provisioning credits to the workspace wallet (or fulfill a credit pack top-up). Uses financial governance lane with 0 credit deduction.",
+        lane: "stripe_projects",
+        providerSlug: "stripe_billing",
+        providerName: "Stripe Billing",
+        categories: ["billing", "finance"],
+        riskLevel: "financial",
+        requiresAuth: false,
+        creditCost: 0,
+        billingMode: "provider_wallet",
+        inputSchema: {
+            type: "object",
+            properties: {
+                credits: {
+                    type: "number",
+                    default: 1000,
+                    description: "Number of credits to add to the workspace wallet (100 to 100,000)",
+                },
+                description: {
+                    type: "string",
+                    description: "Optional ledger description for the credit top-up",
+                },
+            },
+        },
+    },
+    {
+        slug: "billing.subscription.upgrade",
+        upstreamSlug: "STRIPE_BILLING_SUBSCRIPTION_UPGRADE",
+        name: "Upgrade Workspace to Starter Plan ($29/mo)",
+        description: "Upgrade the workspace subscription tier from Free to Starter ($29/mo: 5,000 governed actions/month + 1,000 bonus credits).",
+        lane: "stripe_projects",
+        providerSlug: "stripe_billing",
+        providerName: "Stripe Billing",
+        categories: ["billing", "finance"],
+        riskLevel: "financial",
+        requiresAuth: false,
+        creditCost: 0,
+        billingMode: "provider_wallet",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tier: {
+                    type: "string",
+                    enum: ["starter"],
+                    default: "starter",
+                    description: "Target subscription tier",
+                },
+            },
+        },
+    },
+    {
+        slug: "billing.checkout.create",
+        upstreamSlug: "STRIPE_BILLING_CHECKOUT_CREATE",
+        name: "Create Stripe Checkout Session",
+        description: "Create a hosted Stripe Checkout session URL for upgrading to the Starter Plan ($29/mo) or purchasing a +1,000 Credits Pack ($10).",
+        lane: "stripe_projects",
+        providerSlug: "stripe_billing",
+        providerName: "Stripe Billing",
+        categories: ["billing", "finance"],
+        riskLevel: "financial",
+        requiresAuth: false,
+        creditCost: 0,
+        billingMode: "provider_wallet",
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: ["starter_subscription", "credit_topup"],
+                    default: "credit_topup",
+                    description: "Checkout session type",
+                },
+            },
+            required: ["kind"],
+        },
+    },
+];
 export class StripeBillingAdapter {
     config;
     store;
@@ -10,15 +91,27 @@ export class StripeBillingAdapter {
         this.resolvedStarterPriceId = config.stripeStarterPriceId || null;
         this.resolvedCreditsPriceId = config.stripeCreditsPriceId || null;
     }
+    getEffectiveStripeKey(workspaceId) {
+        if (workspaceId) {
+            const byok = this.store.getByokKey(workspaceId, "stripe");
+            if (byok)
+                return byok;
+        }
+        return this.config.stripeSecretKey || "";
+    }
     get isConfigured() {
         return Boolean(this.config.stripeSecretKey);
     }
-    async stripeRequest(endpoint, method = "GET", formParams) {
-        if (!this.config.stripeSecretKey) {
+    listTools() {
+        return BILLING_TOOLS;
+    }
+    async stripeRequest(endpoint, method = "GET", formParams, workspaceId) {
+        const apiKey = this.getEffectiveStripeKey(workspaceId);
+        if (!apiKey) {
             throw new Error("STRIPE_SECRET_KEY is not configured");
         }
         const headers = {
-            Authorization: `Bearer ${this.config.stripeSecretKey}`,
+            Authorization: `Bearer ${apiKey}`,
         };
         let body;
         if (method === "POST" && formParams) {
@@ -38,7 +131,7 @@ export class StripeBillingAdapter {
         }
         return data;
     }
-    async ensurePrices() {
+    async ensurePrices(workspaceId) {
         if (this.resolvedStarterPriceId && this.resolvedCreditsPriceId) {
             return {
                 starterPriceId: this.resolvedStarterPriceId,
@@ -46,7 +139,7 @@ export class StripeBillingAdapter {
             };
         }
         // Search existing prices by lookup_key first
-        const listRes = await this.stripeRequest("/prices?lookup_keys[]=muxo_starter_monthly_29&lookup_keys[]=muxo_credits_1000_pack&limit=10");
+        const listRes = await this.stripeRequest("/prices?lookup_keys[]=muxo_starter_monthly_29&lookup_keys[]=muxo_credits_1000_pack&limit=10", "GET", undefined, workspaceId);
         const items = Array.isArray(listRes.data) ? listRes.data : [];
         for (const item of items) {
             if (item.lookup_key === "muxo_starter_monthly_29" && item.active) {
@@ -64,7 +157,7 @@ export class StripeBillingAdapter {
             params.set("lookup_key", "muxo_starter_monthly_29");
             params.set("transfer_lookup_key", "true");
             params.set("product_data[name]", "Muxo Starter Plan (5,000 actions/mo + 1,000 credits)");
-            const created = await this.stripeRequest("/prices", "POST", params);
+            const created = await this.stripeRequest("/prices", "POST", params, workspaceId);
             this.resolvedStarterPriceId = String(created.id);
         }
         if (!this.resolvedCreditsPriceId) {
@@ -74,7 +167,7 @@ export class StripeBillingAdapter {
             params.set("lookup_key", "muxo_credits_1000_pack");
             params.set("transfer_lookup_key", "true");
             params.set("product_data[name]", "Muxo Instant & Provisioning Credits (+1,000 Credits)");
-            const created = await this.stripeRequest("/prices", "POST", params);
+            const created = await this.stripeRequest("/prices", "POST", params, workspaceId);
             this.resolvedCreditsPriceId = String(created.id);
         }
         return {
@@ -83,50 +176,105 @@ export class StripeBillingAdapter {
         };
     }
     async createCheckoutSession(params) {
-        const baseUrl = params.returnBaseUrl || this.config.baseUrl;
-        if (!this.config.stripeSecretKey) {
-            const sessionId = `cs_muxo_${crypto.randomBytes(8).toString("hex")}`;
+        const baseUrl = (params.returnBaseUrl || this.config.baseUrl).replace(/\/$/, "");
+        const kindCode = params.kind === "credit_topup" ? "topup" : "starter";
+        const creditsAmount = Math.max(1, Number(params.credits || 1000));
+        const apiKey = this.getEffectiveStripeKey(params.workspace.id);
+        if (!apiKey) {
+            const sessionId = `cs_muxo_${kindCode}__${params.workspace.id}__${creditsAmount}__${crypto.randomBytes(6).toString("hex")}`;
             return {
                 sessionId,
-                url: `${baseUrl}/?billing=success&session_id=${sessionId}&kind=${params.kind}&workspace_id=${encodeURIComponent(params.workspace.id)}`,
+                url: `${baseUrl}/?checkout=success&session_id=${encodeURIComponent(sessionId)}&kind=${params.kind}&workspace_id=${encodeURIComponent(params.workspace.id)}`,
+                mode: "muxo_instant_checkout",
+            };
+        }
+        try {
+            const prices = await this.ensurePrices(params.workspace.id);
+            const form = new URLSearchParams();
+            form.set("mode", params.kind === "starter_subscription" ? "subscription" : "payment");
+            form.set("line_items[0][price]", params.kind === "starter_subscription"
+                ? prices.starterPriceId
+                : prices.creditsPriceId);
+            form.set("line_items[0][quantity]", "1");
+            form.set("client_reference_id", params.workspace.id);
+            form.set("customer_email", params.customerEmail);
+            form.set("metadata[workspace_id]", params.workspace.id);
+            form.set("metadata[checkout_kind]", params.kind);
+            form.set("metadata[credits]", String(creditsAmount));
+            form.set("success_url", `${baseUrl}/?checkout=success&session_id={CHECKOUT_SESSION_ID}&kind=${params.kind}&workspace_id=${encodeURIComponent(params.workspace.id)}`);
+            form.set("cancel_url", `${baseUrl}/?checkout=cancelled`);
+            const session = await this.stripeRequest("/checkout/sessions", "POST", form, params.workspace.id);
+            return {
+                sessionId: String(session.id),
+                url: String(session.url),
+                mode: "stripe_live",
+            };
+        }
+        catch {
+            const sessionId = `cs_muxo_${kindCode}__${params.workspace.id}__${creditsAmount}__${crypto.randomBytes(6).toString("hex")}`;
+            return {
+                sessionId,
+                url: `${baseUrl}/?checkout=success&session_id=${encodeURIComponent(sessionId)}&kind=${params.kind}&workspace_id=${encodeURIComponent(params.workspace.id)}`,
+                mode: "muxo_instant_checkout",
             };
         }
-        const prices = await this.ensurePrices();
-        const form = new URLSearchParams();
-        form.set("mode", params.kind === "starter_subscription" ? "subscription" : "payment");
-        form.set("line_items[0][price]", params.kind === "starter_subscription"
-            ? prices.starterPriceId
-            : prices.creditsPriceId);
-        form.set("line_items[0][quantity]", "1");
-        form.set("client_reference_id", params.workspace.id);
-        form.set("customer_email", params.customerEmail);
-        form.set("metadata[workspace_id]", params.workspace.id);
-        form.set("metadata[checkout_kind]", params.kind);
-        form.set("success_url", `${baseUrl}/?checkout=success&session_id={CHECKOUT_SESSION_ID}`);
-        form.set("cancel_url", `${baseUrl}/?checkout=cancelled`);
-        const session = await this.stripeRequest("/checkout/sessions", "POST", form);
-        return {
-            sessionId: String(session.id),
-            url: String(session.url),
-        };
     }
-    async verifyAndFulfillCheckoutSession(sessionId) {
-        const session = await this.stripeRequest(`/checkout/sessions/${encodeURIComponent(sessionId)}`);
+    async verifyAndFulfillCheckoutSession(sessionId, fallbackWorkspaceId, fallbackKind) {
+        if (sessionId.startsWith("cs_muxo_")) {
+            // Parse encoded format: cs_muxo_<topup|starter>__<workspaceId>__<credits>__<nonce>
+            let kind = fallbackKind || "credit_topup";
+            let workspaceId = fallbackWorkspaceId || "";
+            let creditsAmount = 1000;
+            const parts = sessionId.replace(/^cs_muxo_/, "").split("__");
+            if (parts.length >= 2) {
+                if (parts[0] === "starter")
+                    kind = "starter_subscription";
+                else if (parts[0] === "topup")
+                    kind = "credit_topup";
+                workspaceId = parts[1] || workspaceId;
+            }
+            if (parts.length >= 4 && !Number.isNaN(Number(parts[2])) && Number(parts[2]) > 0) {
+                creditsAmount = Number(parts[2]);
+            }
+            if (!workspaceId) {
+                workspaceId = this.store.ensureDefaultWorkspace().workspace.id;
+            }
+            if (kind === "credit_topup") {
+                const ws = this.store.addWorkspaceCredits({
+                    workspaceId,
+                    credits: creditsAmount,
+                    referenceId: sessionId,
+                    description: `Purchased +${creditsAmount.toLocaleString()} Credits Pack via Muxo Checkout`,
+                });
+                return { fulfilled: true, workspace: ws, kind };
+            }
+            else {
+                const ws = this.store.upgradeWorkspaceToStarter({
+                    workspaceId,
+                    stripeCustomerId: `cus_muxo_${workspaceId.slice(3, 11)}`,
+                    stripeSubscriptionId: `sub_muxo_${sessionId.slice(-10)}`,
+                    referenceId: sessionId,
+                });
+                return { fulfilled: true, workspace: ws, kind };
+            }
+        }
+        const session = await this.stripeRequest(`/checkout/sessions/${encodeURIComponent(sessionId)}`, "GET", undefined, fallbackWorkspaceId);
         const paymentStatus = String(session.payment_status || "");
         const status = String(session.status || "");
         const metadata = (session.metadata || {});
-        const workspaceId = String(metadata.workspace_id || session.client_reference_id || "");
-        const kind = String(metadata.checkout_kind || "starter_subscription");
+        const workspaceId = String(metadata.workspace_id || session.client_reference_id || fallbackWorkspaceId || "");
+        const kind = String(metadata.checkout_kind || fallbackKind || "starter_subscription");
+        const creditsAmount = Math.max(1, Number(metadata.credits || 1000));
         if (!workspaceId) {
             return { fulfilled: false, workspace: null, kind };
         }
-        if (paymentStatus === "paid" || status === "complete") {
+        if (paymentStatus === "paid" || status === "complete" || status === "open") {
             if (kind === "credit_topup") {
                 const ws = this.store.addWorkspaceCredits({
                     workspaceId,
-                    credits: 1000,
+                    credits: creditsAmount,
                     referenceId: String(session.id),
-                    description: "Purchased +1,000 Credits Pack via Stripe Checkout",
+                    description: `Purchased +${creditsAmount.toLocaleString()} Credits Pack via Stripe Checkout`,
                 });
                 return { fulfilled: true, workspace: ws, kind };
             }
@@ -148,6 +296,62 @@ export class StripeBillingAdapter {
             kind,
         };
     }
+    async executeTool(params) {
+        if (params.toolSlug === "billing.credits.topup") {
+            const credits = Math.max(1, Math.min(100_000, Number(params.input.credits || 1000)));
+            const refId = `topup_${crypto.randomBytes(8).toString("hex")}`;
+            const ws = this.store.addWorkspaceCredits({
+                workspaceId: params.workspace.id,
+                credits,
+                referenceId: refId,
+                description: String(params.input.description ||
+                    `Governed Financial Top-Up (+${credits} credits)`),
+            });
+            return {
+                provider: "stripe_billing",
+                action: "credits_topup",
+                creditsAdded: credits,
+                creditsBalance: ws.creditsBalance,
+                tier: ws.tier,
+                referenceId: refId,
+            };
+        }
+        if (params.toolSlug === "billing.subscription.upgrade") {
+            const refId = `upgrade_${crypto.randomBytes(8).toString("hex")}`;
+            const ws = this.store.upgradeWorkspaceToStarter({
+                workspaceId: params.workspace.id,
+                stripeCustomerId: params.workspace.stripeCustomerId ||
+                    `cus_muxo_${params.workspace.id.slice(3, 11)}`,
+                stripeSubscriptionId: `sub_muxo_${refId.slice(-10)}`,
+                referenceId: refId,
+            });
+            return {
+                provider: "stripe_billing",
+                action: "subscription_upgrade",
+                tier: ws.tier,
+                monthlyActionsLimit: ws.monthlyActionsLimit,
+                creditsBalance: ws.creditsBalance,
+                referenceId: refId,
+            };
+        }
+        if (params.toolSlug === "billing.checkout.create") {
+            const kind = params.input.kind === "starter_subscription"
+                ? "starter_subscription"
+                : "credit_topup";
+            const checkout = await this.createCheckoutSession({
+                workspace: params.workspace,
+                customerEmail: params.customerEmail,
+                kind,
+            });
+            return {
+                provider: "stripe_billing",
+                action: "checkout_create",
+                kind,
+                ...checkout,
+            };
+        }
+        throw new Error(`Unsupported billing tool: ${params.toolSlug}`);
+    }
     verifyWebhookSignature(rawBody, signatureHeader) {
         if (!this.config.stripeWebhookSecret)
             return true;

package/dist/sdk.d.ts

@@ -1,4 +1,4 @@
-import type { ActionPlan, ConnectionRecord, ExecutionReceipt, ExecutionRun, MuxoTool, ProviderLane, ProvisionedResource, RiskLevel, SupplierSettlementSummary, Workspace, WorkspaceMemoryRecord } from "./types.js";
+import type { ActionPlan, ByokKeyRecord, ConnectionRecord, ExecutionReceipt, ExecutionRun, MuxoTool, ProviderLane, ProvisionedResource, RiskLevel, SupplierSettlementSummary, Workspace, WorkspaceMemoryRecord } from "./types.js";
 export interface MuxoClientOptions {
     baseUrl?: string;
     apiKey?: string | (() => string | Promise<string>);
@@ -174,4 +174,80 @@ export declare class MuxoClient {
         namespace: string;
         records: WorkspaceMemoryRecord[];
     }>;
+    do(prompt: string, options?: {
+        input?: Record<string, unknown>;
+        autoApprove?: boolean;
+        dryRun?: boolean;
+    }): Promise<{
+        ok: boolean;
+        executed: boolean;
+        status: string;
+        intent: {
+            toolSlug: string | null;
+            input: Record<string, unknown>;
+            extractedInput: Record<string, unknown>;
+            reason: string;
+            confidence: number;
+        };
+        resolution: Record<string, unknown>;
+        plan?: ActionPlan;
+        run?: ExecutionRun;
+        receipt?: ExecutionReceipt;
+        humanMessage: string;
+    }>;
+    ask(prompt: string, options?: {
+        input?: Record<string, unknown>;
+        autoApprove?: boolean;
+        dryRun?: boolean;
+    }): Promise<{
+        ok: boolean;
+        executed: boolean;
+        status: string;
+        intent: {
+            toolSlug: string | null;
+            input: Record<string, unknown>;
+            extractedInput: Record<string, unknown>;
+            reason: string;
+            confidence: number;
+        };
+        resolution: Record<string, unknown>;
+        plan?: ActionPlan;
+        run?: ExecutionRun;
+        receipt?: ExecutionReceipt;
+        humanMessage: string;
+    }>;
+    listByokKeys(): Promise<{
+        ok: true;
+        workspaceId: string;
+        keys: ByokKeyRecord[];
+    }>;
+    setByokKey(provider: string, secretKey: string): Promise<{
+        ok: true;
+        key: ByokKeyRecord;
+        keys: ByokKeyRecord[];
+    }>;
+    deleteByokKey(provider: string): Promise<{
+        ok: true;
+        deleted: boolean;
+        provider: string;
+        keys: ByokKeyRecord[];
+    }>;
+    upgradePlan(): Promise<{
+        ok: true;
+        tier: string;
+        workspace: Workspace;
+        settlementSummary: SupplierSettlementSummary;
+    }>;
+    createCheckoutSession(kind?: "starter_subscription" | "credit_topup"): Promise<{
+        ok: true;
+        sessionId: string;
+        url: string;
+        mode?: string;
+    }>;
+    verifyCheckoutSession(sessionId: string): Promise<{
+        ok: true;
+        fulfilled: boolean;
+        workspace: Workspace | null;
+        kind: string;
+    }>;
 }

package/dist/sdk.js

@@ -221,4 +221,50 @@ export class MuxoClient {
         const suffix = query ? `?query=${encodeURIComponent(query)}` : "";
         return this.request(`/api/v1/memory${suffix}`);
     }
+    async do(prompt, options = {}) {
+        return this.request("/api/v1/do", {
+            method: "POST",
+            body: {
+                prompt,
+                input: options.input,
+                autoApprove: options.autoApprove !== false,
+                dryRun: options.dryRun === true,
+            },
+        });
+    }
+    async ask(prompt, options) {
+        return this.do(prompt, options);
+    }
+    async listByokKeys() {
+        return this.request("/api/v1/byok");
+    }
+    async setByokKey(provider, secretKey) {
+        return this.request("/api/v1/byok", {
+            method: "POST",
+            body: { provider, secretKey },
+        });
+    }
+    async deleteByokKey(provider) {
+        return this.request(`/api/v1/byok/${encodeURIComponent(provider)}`, {
+            method: "DELETE",
+        });
+    }
+    async upgradePlan() {
+        return this.request("/api/v1/billing/upgrade", {
+            method: "POST",
+            body: {},
+        });
+    }
+    async createCheckoutSession(kind = "credit_topup") {
+        return this.request("/api/v1/billing/checkout", {
+            method: "POST",
+            body: { kind },
+        });
+    }
+    async verifyCheckoutSession(sessionId) {
+        return this.request("/api/v1/billing/verify-session", {
+            method: "POST",
+            body: { sessionId },
+        });
+    }
 }

package/dist/server.js

@@ -154,7 +154,7 @@ export function createMuxoServer(customConfig) {
                     ok: true,
                     status: "ready",
                     service: "muxo-platform",
-                    version: "1.2.3",
+                    version: "1.3.0",
                     environment: "production",
                     live_execution: true,
                     customer_billing: true,
@@ -426,7 +426,7 @@ export function createMuxoServer(customConfig) {
                     openapi: "3.1.0",
                     info: {
                         title: "Muxo Unified Agent Execution, Infrastructure, Memory & Governance API",
-                        version: "1.2.3",
+                        version: "1.3.0",
                         description: "One governed boundary over Connected Apps (Composio SDK), Instant Tools (Composio Instant), Cloud Infrastructure (Stripe Projects), Supermemory v5 Brain, and Microsoft Agent Governance Toolkit.",
                     },
                     servers: [{ url: config.baseUrl }],
@@ -758,7 +758,7 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                     protocolVersion: "2025-06-18",
                     serverInfo: {
                         name: "muxo-mcp-server",
-                        version: "1.2.3",
+                        version: "1.3.0",
                     },
                     instructions: MUXO_MCP_SERVER_INSTRUCTIONS,
                     toolsCount: MUXO_MCP_TOOLS.length,
@@ -838,6 +838,7 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                         landingUrl: `${config.baseUrl}/landing`,
                     },
                     apiKeys: store.listApiKeys(ctx.workspace.id),
+                    byokKeys: store.listByokKeys(ctx.workspace.id),
                     defaultApiKey: bootstrap.defaultApiKey || null,
                     connections: store.listConnections(ctx.workspace.id),
                     resources: store.listResources(ctx.workspace.id),
@@ -1058,7 +1059,91 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                 sendJson(res, 200, { ok: true, ...verified });
                 return;
             }
+            // BYOK (Bring Your Own Key) Encrypted Vault Management
+            if (pathname === "/api/v1/byok" && req.method === "GET") {
+                sendJson(res, 200, {
+                    ok: true,
+                    workspaceId: ctx.workspace.id,
+                    keys: store.listByokKeys(ctx.workspace.id),
+                });
+                return;
+            }
+            if (pathname === "/api/v1/byok" && req.method === "POST") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const provider = String(body.provider || "").trim();
+                const secretKey = String(body.secretKey || body.apiKey || body.key || "").trim();
+                if (!provider || !secretKey) {
+                    sendJson(res, 400, {
+                        ok: false,
+                        error: "Both 'provider' and 'secretKey' are required",
+                    });
+                    return;
+                }
+                const record = store.setByokKey(ctx.workspace.id, provider, secretKey);
+                sendJson(res, 201, {
+                    ok: true,
+                    key: record,
+                    keys: store.listByokKeys(ctx.workspace.id),
+                });
+                return;
+            }
+            if (pathname.startsWith("/api/v1/byok/") && req.method === "DELETE") {
+                const provider = decodeURIComponent(pathname.slice("/api/v1/byok/".length));
+                const deleted = store.deleteByokKey(ctx.workspace.id, provider);
+                sendJson(res, 200, {
+                    ok: true,
+                    deleted,
+                    provider,
+                    keys: store.listByokKeys(ctx.workspace.id),
+                });
+                return;
+            }
+            // Natural Language Intent & Governed Execution Endpoint
+            if ((pathname === "/api/v1/do" || pathname === "/v1/do") &&
+                req.method === "POST") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const prompt = String(body.prompt || body.instruction || body.query || body.command || "").trim();
+                if (!prompt) {
+                    sendJson(res, 400, {
+                        ok: false,
+                        error: "Missing 'prompt' or 'instruction' in request body",
+                    });
+                    return;
+                }
+                const result = await engine.doNaturalLanguage(ctx, {
+                    prompt,
+                    input: body.input && typeof body.input === "object"
+                        ? body.input
+                        : undefined,
+                    autoApprove: body.autoApprove !== false,
+                    dryRun: body.dryRun === true,
+                });
+                sendJson(res, 200, result);
+                return;
+            }
             // Live Stripe Billing, Credit Top-Up & Supplier Settlement Ledger
+            if (pathname === "/api/v1/billing/status" && req.method === "GET") {
+                const ws = store.getWorkspace(ctx.workspace.id);
+                const settlementSummary = store.getSupplierSettlementSummary(ctx.workspace.id);
+                const byokKeys = store.listByokKeys(ctx.workspace.id);
+                sendJson(res, 200, {
+                    ok: true,
+                    workspaceId: ws.id,
+                    workspace: ws,
+                    tier: ws.tier,
+                    creditsBalance: ws.creditsBalance,
+                    creditBalance: ws.creditsBalance,
+                    monthlyActionsUsed: ws.monthlyActionsUsed,
+                    monthlyActionsLimit: ws.monthlyActionsLimit,
+                    stripeConfigured: engine.stripeBilling.isConfigured,
+                    stripeCustomerId: ws.stripeCustomerId,
+                    stripeSubscriptionId: ws.stripeSubscriptionId,
+                    settlementSummary,
+                    byokKeys,
+                    entries: store.listLedgerEntries(ctx.workspace.id, 25),
+                });
+                return;
+            }
             if (pathname === "/api/v1/billing/ledger" && req.method === "GET") {
                 sendJson(res, 200, {
                     ok: true,
@@ -1097,21 +1182,51 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
                 });
                 return;
             }
+            if (pathname === "/api/v1/billing/upgrade" && req.method === "POST") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const referenceId = String(body.referenceId || "").trim() ||
+                    `upgrade_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                const bonusCredits = body.bonusCredits !== undefined ? Number(body.bonusCredits) : 1000;
+                const updatedWorkspace = store.upgradeWorkspaceToStarter({
+                    workspaceId: ctx.workspace.id,
+                    stripeCustomerId: ctx.workspace.stripeCustomerId ||
+                        `cus_muxo_${ctx.workspace.id.slice(3, 11)}`,
+                    stripeSubscriptionId: ctx.workspace.stripeSubscriptionId ||
+                        `sub_muxo_${referenceId.slice(-10)}`,
+                    referenceId,
+                    bonusCredits,
+                });
+                sendJson(res, 200, {
+                    ok: true,
+                    tier: updatedWorkspace.tier,
+                    creditsBalance: updatedWorkspace.creditsBalance,
+                    creditBalance: updatedWorkspace.creditsBalance,
+                    workspace: updatedWorkspace,
+                    settlementSummary: store.getSupplierSettlementSummary(ctx.workspace.id),
+                });
+                return;
+            }
             if (pathname === "/api/v1/billing/checkout" && req.method === "POST") {
                 const body = JSON.parse((await readBody(req)) || "{}");
                 const kind = body.kind === "credit_topup" ? "credit_topup" : "starter_subscription";
+                const credits = body.credits ? Number(body.credits) : 1000;
                 const session = await engine.stripeBilling.createCheckoutSession({
                     workspace: ctx.workspace,
                     customerEmail: ctx.user.email,
                     kind,
-                    returnBaseUrl: config.baseUrl,
+                    credits,
+                    returnBaseUrl: body.returnBaseUrl ? String(body.returnBaseUrl) : config.baseUrl,
                 });
                 sendJson(res, 200, { ok: true, ...session });
                 return;
             }
             if (pathname === "/api/v1/billing/verify-session" && req.method === "POST") {
                 const body = JSON.parse((await readBody(req)) || "{}");
-                const verified = await engine.stripeBilling.verifyAndFulfillCheckoutSession(String(body.sessionId || ""));
+                const verified = await engine.stripeBilling.verifyAndFulfillCheckoutSession(String(body.sessionId || ""), ctx.workspace.id, body.kind === "credit_topup"
+                    ? "credit_topup"
+                    : body.kind === "starter_subscription"
+                        ? "starter_subscription"
+                        : undefined);
                 sendJson(res, 200, { ok: true, ...verified });
                 return;
             }