Mux Node SDK

Mux Node SDK (published as @mux/mux-node, with the repo now generating the successor @mux/ts package) is the official server-side client for the Mux API, giving Node.js and TypeScript projects a fully typed way to create and manage video assets, live streams, and playback policies through Mux Video, and to query engagement and quality metrics through Mux Data. The client is generated from Mux’s OpenAPI spec via Stainless, so every resource, request parameter, and response field ships with accurate TypeScript types and inline documentation that surfaces directly in editor tooltips.

Beyond the generated REST wrapper, the SDK adds hand-written ergonomics specific to Mux’s product: JWT helpers for signing playback, thumbnail, GIF, and storyboard tokens (including a batched helper that signs several token types at once for use with Mux Player), and webhook signature verification for validating incoming Mux event payloads. A typed error hierarchy maps HTTP status codes to specific exception classes, and the package ships as both CommonJS and ESM builds with zero runtime dependencies.

What You Get

• A single Mux client class configured from MUX_TOKEN_ID/MUX_TOKEN_SECRET env vars (or explicit options) that exposes video, data, system, and webhooks resource namespaces
• Full TypeScript types for every request parameter and response field across the Mux Video and Mux Data APIs, generated from Mux’s OpenAPI spec
• JWT helpers (mux.jwt.signPlaybackId, signViewerCounts) for signing playback, thumbnail, GIF, storyboard, and DRM-license tokens, including a batched multi-token form for Mux Player props
• Webhook signature verification (mux.webhooks.unwrap) for validating and parsing incoming Mux event payloads
• A typed error hierarchy (BadRequestError, AuthenticationError, NotFoundError, etc.) mapped from HTTP status codes, plus built-in retry and pagination handling for list endpoints
• Dual CommonJS/ESM builds with zero runtime dependencies, plus a bundled CLI (mux-ts)

Common Use Cases

• Uploading or ingesting video (by URL or direct upload) and creating Mux assets with specific encoding, captioning, and playback-policy settings
• Signing short-lived playback tokens so an app can serve private/DRM-protected video and thumbnails without exposing a permanent signing key client-side
• Verifying and handling Mux webhook events (asset ready, live stream started, upload errored, etc.) in a Node.js server or serverless function
• Pulling Mux Data metrics (views, quality scores, real-time dashboards) into an internal analytics or monitoring pipeline
• Managing live streams programmatically — creating a live stream, rotating its stream key, and reading its current playback status

Under The Hood

Architecture The Mux client (src/client.ts) constructs lazily-instantiated resource namespaces — Video, Data, System, Webhooks, Robots — each defined under src/resources/, on top of a shared internal transport layer (src/internal/: platform-detected fetch shims, request-options normalization, response parsing, header building, typed errors) and a common APIResource base (src/resource.ts). List endpoints return AbstractPage subclasses (CursorPageResponse, PageWithTimeframeResponse, PageWithTotalResponse in src/core/pagination.ts) that support for await iteration, and every request returns an APIPromise (src/core/api-promise.ts) that can resolve to parsed data, the raw Response, or both via .withResponse(). Hand-written modules — jwt.ts for token signing and webhooks.ts for signature verification — sit alongside the generated resources as Mux-specific additions. This layering means transport-level changes (internal/shims, internal/request-options) would ripple through every resource, while individual resource or hand-written-helper changes stay isolated.

Tech Stack Written in TypeScript 5.8 with no runtime dependencies, compiled via tsc-multi (a Stainless-maintained fork) into parallel CJS (dist/index.js) and ESM (dist/index.mjs) builds exposed through a conditional exports map. Platform interoperability (Node, Deno, browser) is handled through internal/shims and internal/detect-platform rather than a bundler dependency. Tooling includes Jest with @swc/jest for fast TypeScript test transpilation, ESLint 9’s flat config with typescript-eslint and eslint-plugin-unused-imports, Prettier 3, and publint/@arethetypeswrong/cli to validate the published package’s exports and type resolution before release. CI (ci.yml) and release-please.yml/publish-npm.yml automate testing and semantic-release-style publishing.

Code Quality The repo carries over 50 test files mirroring the resource tree 1:1 under tests/api-resources/, each testing both a minimal required-params call and a fully-populated params call against a local mock API server (TEST_API_BASE_URL, defaulting to a Prism-style mock on 127.0.0.1:4010), plus separate unit tests for core utilities like base64 encoding, header building, and query-string stringification. Errors are explicit and typed rather than swallowed — every HTTP status maps to a specific APIError subclass with a constructed message — and the generated resource files carry extensive inline JSDoc on every parameter and response field. Linting and formatting are enforced via scripts/lint/scripts/format, with CI running on every push.

API Design The client mirrors Mux’s REST API almost 1:1 as chained resource namespaces (mux.video.assets.create, mux.data.*), keeping it discoverable to anyone already familiar with Mux’s REST docs, while the real ergonomic wins are Mux-specific: JWT signing helpers collapse a multi-step manual token-construction process into one call, a batched form of signPlaybackId returns all the token props Mux Player expects in one shape, and webhook verification is a single typed call. Getting started requires only two environment variables and zero required constructor arguments.