Library usage

Use @mulerouter/core to embed MuleRouter calls directly in a TypeScript program

The CLI is a thin layer over @mulerouter/core. The same package is published independently — install it when you want to call MuleRouter from a Node.js, Bun, or TypeScript application without shelling out.

npm install @mulerouter/core

The package has zero runtime dependencies and ships with full TypeScript types.

Minimal example

import {
  APIClient,
  createAndPollTask,
  loadConfig,
  processImageParams,
  registry,
} from "@mulerouter/core";

const config = loadConfig({ site: "mulerouter" });
const client = new APIClient(config);

const endpoint = registry.get("alibaba/wan2.6-t2i", "generation");
if (!endpoint) throw new Error("endpoint not registered");

const body = processImageParams({
  prompt: "A blooming cherry tree at dusk",
  size: "1280*1280",
});

const result = await createAndPollTask({
  client,
  endpointPath: endpoint.apiPath,
  requestBody: body,
  resultKey: endpoint.resultKey,
});

if (result.status === "succeeded") {
  console.log(result.results); // string[] of asset URLs
} else {
  console.error(result.status, result.error);
}

Public API surface

import {
  // Config
  loadConfig,
  getConfigHelp,
  loadEnvFile,

  // HTTP client
  APIClient,

  // Model registry
  registry,
  ModelRegistry,
  registerEndpoint,

  // Tasks
  createAndPollTask,
  pollTask,
  parseTaskResponse,
  isSuccessStatus,
  isTerminalStatus,

  // Image helpers
  processImageParams,
  isImageParam,
  validateImagePath,

  // Utilities
  toCliFlag,
  VERSION,
} from "@mulerouter/core";

import type {
  Site,           // "mulerouter" | "mulerun"
  InputType,      // "text" | "image" | "video" | "audio"
  OutputType,     // "image" | "video" | "text" | "audio"
  ModelParameter,
  ModelEndpoint,
  Config,
  APIResponse,
  TaskStatus,
  TaskResult,
} from "@mulerouter/core";

Key functions

loadConfig(options?)

Resolves apiKey, baseUrl, site, plus default timeout (120_000 ms) and retry budget (3). Same priority chain as the CLI: arguments → environment variables → .env.

new APIClient(config)

A small fetch-based client with:

• Bearer-token auth via the configured API key
• Automatic JSON encoding
• Exponential-backoff retry on transient failures (5xx, network errors)
• post(path, body) and get(path) returning APIResponse

createAndPollTask({...})

Submits a POST to endpointPath and polls every interval ms (default 20 000) until the task reaches a terminal state or maxWait (default 900 000 ms) elapses. Set verbose: true to log per-poll status lines to stderr.

pollTask({...})

Same poller, against an already-created task identified by taskPath and taskId.

processImageParams(body)

Walks a request body, finds any image-shaped parameter, and converts local file paths to base64 data URIs. Idempotent for URLs and data: URIs.

registry

Singleton catalog of every endpoint that has been imported. The registry is populated as a side effect of importing @mulerouter/core (which loads models/index.ts and every provider module). Useful methods:

Method	Returns
registry.get(modelId, action)	A single ModelEndpoint or undefined
registry.findByModelId(modelId)	Every action registered under that model
registry.listAll()	Everything
registry.listForSite("mulerun")	Filtered by site
registry.listByProvider("alibaba")	Filtered by provider
registry.listByOutputType("video")	Filtered by output type
registry.listByTag("SOTA")	Filtered by tag
registry.getProviders()	Sorted unique provider names

Status helpers

import { isSuccessStatus, isTerminalStatus } from "@mulerouter/core";

isSuccessStatus(result.status);   // succeeded | completed
isTerminalStatus(result.status);  // success states + failed

Naming convention

In code, model parameter names use snake_case (matching the wire format). The CLI converts to kebab-case for flags via toCliFlag(name) — useful if you are building tooling that mirrors the CLI’s UX.

import { toCliFlag } from "@mulerouter/core";

toCliFlag("negative_prompt");  // "negative-prompt"
toCliFlag("aspect_ratio");     // "aspect-ratio"

Versioning

The CLI and core packages are released in lockstep. The version string is exported as VERSION and is what the CLI prints for mulerouter --version.