@muxoai/sdk 1.3.0 → 1.4.3

package/dist/sdk.js

@@ -1,3 +1,21 @@
+/** Error thrown for any non-OK Muxo API response. Carries the machine-readable code and payload. */
+export class MuxoApiError extends Error {
+    status;
+    code;
+    url;
+    checkoutUrl;
+    data;
+    constructor(status, payload) {
+        super(String(payload.error || `Muxo request failed with HTTP ${status}`));
+        this.name = "MuxoApiError";
+        this.status = status;
+        this.code = typeof payload.code === "string" ? payload.code : undefined;
+        this.url = typeof payload.url === "string" ? payload.url : undefined;
+        this.checkoutUrl =
+            typeof payload.checkoutUrl === "string" ? payload.checkoutUrl : undefined;
+        this.data = payload;
+    }
+}
 export class MuxoClient {
     baseUrl;
     apiKeyResolver;
@@ -41,7 +59,7 @@ export class MuxoClient {
         });
         const payload = (await res.json());
         if (!res.ok || payload.ok === false) {
-            throw new Error(String(payload.error || `Muxo request failed with HTTP ${res.status}`));
+            throw new MuxoApiError(res.status, payload);
         }
         return payload;
     }
@@ -52,6 +70,26 @@ export class MuxoClient {
             harness: params.harness || "muxo-sdk",
         });
     }
+    static async register(params, baseUrl = "https://app.muxo.ai") {
+        const client = new MuxoClient({ baseUrl });
+        return client.register(params);
+    }
+    static async login(params, baseUrl = "https://app.muxo.ai") {
+        const client = new MuxoClient({ baseUrl });
+        return client.login(params);
+    }
+    async register(params) {
+        return this.request("/api/v1/auth/register", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async login(params) {
+        return this.request("/api/v1/auth/login", {
+            method: "POST",
+            body: params,
+        });
+    }
     async signupAgent(params) {
         return this.request("/api/v1/agents/signup", {
             method: "POST",
@@ -80,6 +118,10 @@ export class MuxoClient {
         if (rpcRes.error) {
             throw new Error(rpcRes.error.message || "MCP call failed");
         }
+        if (rpcRes.result?.isError) {
+            const errObj = rpcRes.result.structuredContent;
+            throw new Error(String(errObj?.error || rpcRes.result.content?.[0]?.text || "MCP tool execution failed"));
+        }
         if (rpcRes.result?.structuredContent) {
             return rpcRes.result.structuredContent;
         }
@@ -111,9 +153,26 @@ export class MuxoClient {
             body: params,
         });
     }
-    async approvePlan(planId) {
+    async getPlan(planId, options) {
+        const qs = new URLSearchParams();
+        if (options?.waitForApproval)
+            qs.set("wait_for_approval", "true");
+        if (options?.timeoutSeconds !== undefined) {
+            qs.set("timeout_seconds", String(options.timeoutSeconds));
+        }
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/plans/${encodeURIComponent(planId)}${suffix}`);
+    }
+    async waitForPlanApproval(planId, timeoutSeconds = 25) {
+        return this.request(`/api/v1/plans/${encodeURIComponent(planId)}/wait`, {
+            method: "POST",
+            body: { timeoutSeconds },
+        });
+    }
+    async approvePlan(planId, decision = "approved") {
         return this.request(`/api/v1/plans/${encodeURIComponent(planId)}/approve`, {
             method: "POST",
+            body: { decision },
         });
     }
     async executePlan(planId) {
@@ -121,16 +180,39 @@ export class MuxoClient {
             method: "POST",
         });
     }
+    async getRun(runId) {
+        return this.request(`/api/v1/runs/${encodeURIComponent(runId)}`);
+    }
+    async cancelRun(runId, reason) {
+        return this.request(`/api/v1/runs/${encodeURIComponent(runId)}/cancel`, {
+            method: "POST",
+            body: reason ? { reason } : {},
+        });
+    }
     async exec(toolSlug, input = {}, options = {}) {
         const planned = await this.planAction({
             toolSlug,
             input,
             reason: options.reason,
+            fundingMode: options.fundingMode,
         });
         let plan = planned.plan;
         if (plan.approvalStatus === "pending_approval" && options.approve) {
-            const approved = await this.approvePlan(plan.id);
-            plan = approved.plan;
+            try {
+                const approved = await this.approvePlan(plan.id);
+                plan = approved.plan;
+            }
+            catch (err) {
+                if (err instanceof MuxoApiError && err.code === "human_required") {
+                    throw new MuxoApiError(err.status, {
+                        ...err.data,
+                        planId: plan.id,
+                        approvalUrl: err.url,
+                        error: `Plan ${plan.id} needs approval from a signed-in person at ${err.url || "the Muxo console"}; API keys cannot approve plans.`,
+                    });
+                }
+                throw err;
+            }
         }
         const executed = await this.executePlan(plan.id);
         return {
@@ -151,8 +233,29 @@ export class MuxoClient {
             valid: isOk,
             verified: isOk,
             receipt: res.receipt,
+            agenticReceiptValid: res.agenticReceiptValid,
+            explanation: res.explanation,
         };
     }
+    async verifyReceiptChain(limit = 100) {
+        return this.request(`/api/v1/receipts/verify-chain?limit=${encodeURIComponent(String(limit))}`);
+    }
+    async getMemoryGraph(queryOrOptions) {
+        const opts = typeof queryOrOptions === "string"
+            ? { query: queryOrOptions }
+            : queryOrOptions || {};
+        const qs = new URLSearchParams();
+        if (opts.query)
+            qs.set("query", opts.query);
+        if (opts.asOf)
+            qs.set("as_of", opts.asOf);
+        if (opts.focalEntity)
+            qs.set("focal_entity", opts.focalEntity);
+        if (opts.maxHops !== undefined)
+            qs.set("max_hops", String(opts.maxHops));
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/memory/graph${suffix}`);
+    }
     async startConnection(paramsOrProvider) {
         const body = typeof paramsOrProvider === "string"
             ? { provider: paramsOrProvider }
@@ -199,7 +302,13 @@ export class MuxoClient {
         };
     }
     async getBillingStatus() {
-        return this.getSettlements();
+        const res = await this.request("/api/v1/billing/status");
+        if (res.settlementSummary &&
+            res.settlementSummary.totalCustomerChargedCredits === undefined) {
+            res.settlementSummary.totalCustomerChargedCredits =
+                res.settlementSummary.totalCreditsConsumed;
+        }
+        return res;
     }
     async settlements() {
         const res = await this.getSettlements();
@@ -221,14 +330,116 @@ export class MuxoClient {
         const suffix = query ? `?query=${encodeURIComponent(query)}` : "";
         return this.request(`/api/v1/memory${suffix}`);
     }
+    async addMemory(paramsOrContent) {
+        const body = typeof paramsOrContent === "string"
+            ? { title: paramsOrContent.slice(0, 60), content: paramsOrContent }
+            : paramsOrContent;
+        return this.request("/api/v1/memory", {
+            method: "POST",
+            body,
+        });
+    }
+    async deleteMemory(id) {
+        return this.request(`/api/v1/memory/${encodeURIComponent(id)}`, {
+            method: "DELETE",
+        });
+    }
+    async getMemoryFacts(options = {}) {
+        const opts = typeof options === "boolean" ? { includeHistorical: options } : options;
+        const params = new URLSearchParams();
+        params.set("historical", opts.includeHistorical === false ? "false" : "true");
+        if (opts.query)
+            params.set("query", opts.query);
+        if (opts.subject)
+            params.set("subject", opts.subject);
+        if (opts.predicate)
+            params.set("predicate", opts.predicate);
+        if (opts.limit)
+            params.set("limit", String(opts.limit));
+        return this.request(`/api/v1/memory/facts?${params.toString()}`);
+    }
+    async listTemporalFacts(options) {
+        return this.getMemoryFacts(options);
+    }
+    async forgetMemory(queryOrParams) {
+        const query = (typeof queryOrParams === "string" ? queryOrParams : queryOrParams.query)?.trim();
+        if (!query) {
+            throw new Error("forgetMemory requires a non-empty query");
+        }
+        return this.request("/api/v1/memory/forget", {
+            method: "POST",
+            body: { query },
+        });
+    }
+    async getGovernanceStatus() {
+        return this.request("/api/v1/governance");
+    }
+    async getGuardrails() {
+        return this.request("/api/v1/guardrails");
+    }
+    async setGuardrail(promptOrParams) {
+        const prompt = typeof promptOrParams === "string"
+            ? promptOrParams
+            : promptOrParams.prompt;
+        return this.request("/api/v1/guardrails", {
+            method: "POST",
+            body: { prompt },
+        });
+    }
+    async resetGuardrails() {
+        return this.request("/api/v1/guardrails", {
+            method: "POST",
+            body: { reset: true },
+        });
+    }
+    async setKillSwitch(action, reason) {
+        return this.request("/api/v1/governance/kill-switch", {
+            method: "POST",
+            body: reason ? { action, reason } : { action },
+        });
+    }
+    async scanContext(contentOrParams) {
+        const body = typeof contentOrParams === "string"
+            ? { content: contentOrParams }
+            : contentOrParams;
+        return this.request("/api/v1/governance/scan-context", {
+            method: "POST",
+            body,
+        });
+    }
+    async updatePolicy(policy) {
+        return this.request("/api/v1/policy", {
+            method: "POST",
+            body: policy,
+        });
+    }
+    async getPolicy() {
+        return this.request("/api/v1/policy");
+    }
+    async getContext(query) {
+        const suffix = query ? `?query=${encodeURIComponent(query)}` : "";
+        return this.request(`/api/v1/context${suffix}`);
+    }
+    async listReceipts(limit = 25) {
+        return this.request(`/api/v1/receipts?limit=${encodeURIComponent(String(limit))}`);
+    }
+    async remember(instruction) {
+        return this.request("/api/v1/memory", {
+            method: "POST",
+            body: { prompt: instruction },
+        });
+    }
     async do(prompt, options = {}) {
+        const isDryRun = options.dryRun === true || options.planOnly === true;
         return this.request("/api/v1/do", {
             method: "POST",
             body: {
                 prompt,
                 input: options.input,
                 autoApprove: options.autoApprove !== false,
-                dryRun: options.dryRun === true,
+                dryRun: isDryRun,
+                planOnly: isDryRun,
+                fundingMode: options.fundingMode,
             },
         });
     }
@@ -249,16 +460,50 @@ export class MuxoClient {
             method: "DELETE",
         });
     }
-    async upgradePlan() {
-        return this.request("/api/v1/billing/upgrade", {
+    /** Lists plans, prices, and credit packs. No auth required. */
+    async getPlans() {
+        return this.request("/api/v1/billing/plans");
+    }
+    /**
+     * Moves the workspace to a plan. A first subscription returns a Stripe checkout URL
+     * (`payment_required`); changing an existing subscription returns a billing-portal URL.
+     * Plan changes are confirmed by a signed-in person; API keys get `human_required`.
+     */
+    async upgradePlan(options = {}) {
+        try {
+            return await this.request("/api/v1/billing/upgrade", {
+                method: "POST",
+                body: {
+                    tier: options.tier || "starter",
+                    interval: options.interval || "month",
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof MuxoApiError &&
+                (err.code === "payment_required" || err.code === "human_required")) {
+                return err.data;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Opens the Stripe billing portal to manage payment details, switch plans, or cancel.
+     * Signed-in people only; API keys get a `human_required` MuxoApiError.
+     */
+    async openBillingPortal() {
+        return this.request("/api/v1/billing/portal", {
             method: "POST",
             body: {},
         });
     }
-    async createCheckoutSession(kind = "credit_topup") {
+    async createCheckoutSession(kind = "credit_topup", optionsOrCredits) {
+        const opts = typeof optionsOrCredits === "number"
+            ? { credits: optionsOrCredits }
+            : optionsOrCredits || {};
         return this.request("/api/v1/billing/checkout", {
             method: "POST",
-            body: { kind },
+            body: { kind, ...opts },
         });
     }
     async verifyCheckoutSession(sessionId) {
@@ -267,4 +512,288 @@ export class MuxoClient {
             body: { sessionId },
         });
     }
+    // Stripe v2 Provisioning API (`Stripe-Version: 2026-09-30.preview`) SDK Methods
+    async createProvisioningConnectedAccount(params) {
+        return this.request("/api/v1/provisioning/connected_accounts", {
+            method: "POST",
+            body: params || {},
+        });
+    }
+    async getProvisioningConnectedAccount(accountId) {
+        if (accountId) {
+            return this.request(`/api/v1/provisioning/connected_accounts/${encodeURIComponent(accountId)}`);
+        }
+        return this.request("/api/v1/provisioning/connected_accounts");
+    }
+    async createProvisioningConnectedAccountLink(params) {
+        return this.request("/api/v1/provisioning/connected_account_links", {
+            method: "POST",
+            body: params || {},
+        });
+    }
+    async createProvisioningConnectedAccountSession(params) {
+        return this.request("/api/v1/provisioning/connected_account_sessions", {
+            method: "POST",
+            body: params || {},
+        });
+    }
+    async checkProvisioningEligibility() {
+        return this.request("/api/v1/provisioning/eligibility");
+    }
+    async listProvisioningProviders(params) {
+        const qs = new URLSearchParams();
+        if (params?.catalog)
+            qs.set("catalog", params.catalog);
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.page)
+            qs.set("page", params.page);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/provisioning/catalog/providers${suffix}`);
+    }
+    async listProvisioningServices(params) {
+        const qs = new URLSearchParams();
+        if (params?.catalog)
+            qs.set("catalog", params.catalog);
+        if (params?.provider_name)
+            qs.set("provider_name", params.provider_name);
+        if (params?.provider_id)
+            qs.set("provider_id", params.provider_id);
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.page)
+            qs.set("page", params.page);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/provisioning/catalog/services${suffix}`);
+    }
+    async getProvisioningPaymentProfile(params) {
+        const qs = new URLSearchParams();
+        if (params?.provider)
+            qs.set("provider", params.provider);
+        if (params?.livemode !== undefined)
+            qs.set("livemode", String(params.livemode));
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/provisioning/payment_profile${suffix}`);
+    }
+    async createProvisioningPaymentMethodRequest(params) {
+        return this.request("/api/v1/provisioning/payment_method_requests", {
+            method: "POST",
+            body: params || {},
+        });
+    }
+    async listProvisioningProviderConnections(params) {
+        const qs = new URLSearchParams();
+        if (params?.provider)
+            qs.set("provider", params.provider);
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.page)
+            qs.set("page", params.page);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/provisioning/provider_connections${suffix}`);
+    }
+    async createProvisioningProviderConnectionRequest(params) {
+        return this.request("/api/v1/provisioning/provider_connection_requests", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async listProvisioningProjects(params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.page)
+            qs.set("page", params.page);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/provisioning/projects${suffix}`);
+    }
+    async createProvisioningProject(params) {
+        return this.request("/api/v1/provisioning/projects", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async listProvisioningResources(params) {
+        const qs = new URLSearchParams();
+        if (params?.project)
+            qs.set("project", params.project);
+        if (params?.provider)
+            qs.set("provider", params.provider);
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.page)
+            qs.set("page", params.page);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/provisioning/resources${suffix}`);
+    }
+    async createProvisioningResource(params) {
+        return this.request("/api/v1/provisioning/resources", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async revealResourceAccessConfiguration(resourceId) {
+        return this.request(`/api/v1/provisioning/resources/${encodeURIComponent(resourceId)}/reveal_access_configuration`, {
+            method: "POST",
+            body: {},
+        });
+    }
+    async getResourceSecrets(resourceId) {
+        return this.request(`/api/v1/resources/${encodeURIComponent(resourceId)}/secrets`);
+    }
+    // ---------------------------------------------------------------------------
+    // Multi-Workspace & Team API Key Onboarding
+    // ---------------------------------------------------------------------------
+    async listWorkspaces() {
+        return this.request("/api/v1/workspaces");
+    }
+    async createWorkspace(params) {
+        return this.request("/api/v1/workspaces", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async switchWorkspace(workspaceId) {
+        return this.request("/api/v1/workspaces/switch", {
+            method: "POST",
+            body: { workspaceId },
+        });
+    }
+    async joinWorkspaceWithApiKey(apiKey) {
+        return this.request("/api/v1/workspaces/join", {
+            method: "POST",
+            body: { apiKey },
+        });
+    }
+    async onboardTeam(params) {
+        return this.request("/api/v1/workspaces/onboard-team", {
+            method: "POST",
+            body: params,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Stripe v2 Billing Meter Streams, Event Destinations, Composio Toolkits/Triggers, & Cloudflare Workflows
+    // ---------------------------------------------------------------------------
+    async updateProvisioningSpendLimit(params) {
+        return this.request("/api/v1/provisioning/payment_profile/update_limit", {
+            method: "POST",
+            body: {
+                usage_limits: {
+                    max_amount: String(params.max_amount),
+                    currency: params.currency || "usd",
+                    recurring_interval: params.recurring_interval || "month",
+                },
+                provider: params.provider,
+            },
+        });
+    }
+    async createProvisioningEventDestination(params) {
+        return this.request("/api/v1/provisioning/event_destinations", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async recordBillingMeterEvent(params) {
+        return this.request("/api/v1/billing/meter_events", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async listBillingMeterEvents(limit = 50) {
+        return this.request(`/api/v1/billing/meter_events?limit=${limit}`);
+    }
+    async listToolkits(params) {
+        const qs = new URLSearchParams();
+        if (params?.category)
+            qs.set("category", params.category);
+        if (params?.search)
+            qs.set("search", params.search);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/toolkits${suffix}`);
+    }
+    async createCustomAuthConfig(params) {
+        return this.request("/api/v1/connections/auth-configs", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async listTriggers(provider) {
+        const suffix = provider ? `?provider=${encodeURIComponent(provider)}` : "";
+        return this.request(`/api/v1/triggers${suffix}`);
+    }
+    async enableTrigger(params) {
+        return this.request("/api/v1/triggers", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async ingestTriggerWebhook(params) {
+        return this.request("/api/v1/triggers/webhook", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async executeBatchPlans(params) {
+        return this.request("/api/v1/plans/batch", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async searchMemoryHybrid(query, limit = 10) {
+        return this.request(`/api/v1/memory/hybrid?query=${encodeURIComponent(query)}&limit=${limit}`);
+    }
+    async startDurableWorkflow(params) {
+        return this.request("/api/v1/workflows", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async advanceDurableWorkflow(workflowId, eventPayload) {
+        return this.request(`/api/v1/workflows/${encodeURIComponent(workflowId)}/advance`, {
+            method: "POST",
+            body: eventPayload || {},
+        });
+    }
+    async exportGovernanceArchive() {
+        return this.request("/api/v1/governance/archive");
+    }
+    async getWorkflowHistory(workflowId) {
+        return this.request(`/api/v1/workflows/${encodeURIComponent(workflowId)}/history`);
+    }
+    async signalDurableWorkflow(workflowId, signalName, payload) {
+        return this.request(`/api/v1/workflows/${encodeURIComponent(workflowId)}/signal`, {
+            method: "POST",
+            body: { signalName, payload: payload || {} },
+        });
+    }
+    async rollbackDurableWorkflow(workflowId, params) {
+        return this.request(`/api/v1/workflows/${encodeURIComponent(workflowId)}/rollback`, {
+            method: "POST",
+            body: params || {},
+        });
+    }
+    async getCedarPolicy() {
+        return this.request("/api/v1/governance/cedar");
+    }
+    async evaluateCedarPolicy(params) {
+        return this.request("/api/v1/governance/cedar/evaluate", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async getOtelTraces(limit = 25) {
+        return this.request(`/api/v1/telemetry/otlp?limit=${limit}`);
+    }
+    async listPlaybooks() {
+        return this.request("/api/v1/playbooks");
+    }
+    async runPlaybook(slug, input) {
+        return this.request(`/api/v1/playbooks/${encodeURIComponent(slug)}/run`, {
+            method: "POST",
+            body: { input: input || {} },
+        });
+    }
+    async getRoiAnalytics() {
+        return this.request("/api/v1/analytics/roi");
+    }
 }