muxinc/mux-ts

This library provides convenient access to the Mux REST API from server-side TypeScript or JavaScript.
The REST API documentation can be found on docs.mux.com. The full API of this library can be found in api.md.
Note: As of v14 of mux-node-sdk, we have changed some internal workings of the SDKs. You can read more about this here.
MCP Server
Use the Mux MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
> Note: You may need to set environment variables in your MCP client.
Installation
Usage
The full API of this library can be found in api.md.
Request & Response types
This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
JWT Helpers (API Reference)
You can use any JWT-compatible library, but we've included some light helpers in the SDK to make it easier to get up and running.
Signing multiple JWTs at once
In cases you need multiple tokens, like when using Mux Player, things can get unwieldy pretty quickly. For example,
To simplify this use-case, you can provide multiple types to signPlaybackId to recieve multiple tokens. These tokens are provided in a format that Mux Player can take as props:
If you would like to provide params to a single token (e.g., if you would like to have a thumbnail time), you can provide [type, typeParams] instead of type:
Parsing Webhook payloads
To validate that the given payload was sent by Mux and parse the webhook payload for use in your application,
you can use the mux.webhooks.unwrap utility method.
This method accepts a raw body string and a list of headers. As long as you have set your webhookSecret in the
appropriate configuration property when instantiating the library, all webhooks will be verified for authenticity automatically.
The following example shows how you can handle a webhook using a Next.js app directory API route:
Verifying Webhook Signatures
Verifying Webhook Signatures is _optional but encouraged_. Learn more in our Webhook Security Guide
Note that when passing in the payload (body) you want to pass in the raw un-parsed request body, not the parsed JSON. Here's an example if you are using express.
Handling errors
When the library is unable to connect to the API,
or if the API returns a non-success status code (i.e., 4xx or 5xx response),
a subclass of APIError will be thrown:
Error codes are as follows:
| Status Code | Error Type |
| ----------- | -------------------------- |
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
| N/A | APIConnectionError |
Retries
Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
429 Rate Limit, and >=500 Internal errors will all be retried by default.
You can use the maxRetries option to configure or disable this:
Timeouts
Requests time out after 1 minute by default. You can configure this with a timeout option:
On timeout, an APIConnectionTimeoutError is thrown.
Note that requests which time out will be retried twice by default.
Auto-pagination
List methods in the Mux API are paginated.
You can use the for await … of syntax to iterate through items across all pages: