release: 12.0.0 (#586)

* feat: Add progress API fields to the asset model (#328)

* chore(docs): grammar improvements

* chore: configure new SDK language

* chore(api): remove webhooks from mcp

* feat: Add live stream metadata (#351)

* chore: improve docs for MCP servers

* fix(mcp): fix cursor schema transformation issue with recursive references

* fix(mcp): include description in dynamic tool search

* chore: improve publish-npm script --latest tag logic

* feat(mcp): include http information in tools

* chore(mcp): remove duplicate assignment

* chore(api): mark some methods as deprecated

* docs(pagination): improve naming

* chore(docs): use top-level-await in example snippets

* feat(mcp): implement support for binary responses

* chore(mcp): provides high-level initMcpServer function and exports known clients

* fix: publish script — handle NPM errors correctly

* chore(internal): make base APIResource abstract

* feat(mcp): set X-Stainless-MCP header

* feat(client): add support for endpoint-specific base URLs

* chore(ci): enable for pull requests

* fix(client): correct webhooks types

* refactor(types): replace Record with mapped types

* fix(ci): release-doctor — report correct token name

* feat(mcp): fallback for void-typed methods

* chore: upgrade node in upload step (#354)

* codegen metadata

* chore(ci): only run for pushes and fork pull requests

* codegen metadata

* feat(api): expose playback APIs

* codegen metadata

* codegen metadata

* chore: bump node to 22 in tool-versions

* feat: add new copy_overlays asset option (#355)

* update node in actions steps

* chore: update mcp package name

* release: 12.0.0

* update changelog

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>
Co-authored-by: Justin Sanford <[email protected]>

Author: stainless-app[bot]

.github/workflows/ci.yml

@@ -7,19 +7,24 @@ on:
       - 'integrated/**'
       - 'stl-preview-head/**'
       - 'stl-preview-base/**'
+  pull_request:
+    branches-ignore:
+      - 'stl-preview-head/**'
+      - 'stl-preview-base/**'
 
 jobs:
   lint:
     timeout-minutes: 10
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/mux-node' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
       - uses: actions/checkout@v4
 
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '22'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
@@ -31,6 +36,7 @@ jobs:
     timeout-minutes: 5
     name: build
     runs-on: ${{ github.repository == 'stainless-sdks/mux-node' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     permissions:
       contents: read
       id-token: write
@@ -40,7 +46,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '22'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
@@ -66,16 +72,20 @@ jobs:
     timeout-minutes: 10
     name: test
     runs-on: ${{ github.repository == 'stainless-sdks/mux-node' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
       - uses: actions/checkout@v4
 
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
 
+      - name: Build
+        run: ./scripts/build
+
       - name: Run tests
         run: ./scripts/test

.github/workflows/publish-npm.yml

@@ -4,6 +4,10 @@
 name: Publish NPM
 on:
   workflow_dispatch:
+    inputs:
+      path:
+        description: The path to run the release in, e.g. '.' or 'packages/mcp-server'
+        required: true
 
   release:
     types: [published]
@@ -17,16 +21,21 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Install dependencies
         run: |
           yarn install
 
       - name: Publish to NPM
         run: |
-          bash ./bin/publish-npm
+          if [ -n "${{ github.event.inputs.path }}" ]; then
+            PATHS_RELEASED='[\"${{ github.event.inputs.path }}\"]'
+          else
+            PATHS_RELEASED='[\".\", \"packages/mcp-server\"]'
+          fi
+          yarn tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }"
         env:
           NPM_TOKEN: ${{ secrets.MUX_NPM_TOKEN || secrets.NPM_TOKEN }}

.prettierignore

@@ -4,4 +4,4 @@ CHANGELOG.md
 /deno
 
 # don't format tsc output, will break source maps
-/dist
+dist

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "11.1.0"
+  ".": "12.0.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 97
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/mux%2Fmux-fe7095c6cd410ecd391f6810083a35d9411a2d9772042eaefed534fd51cd9599.yml
-openapi_spec_hash: 104a03331ba4c7f753f583fdb852de11
-config_hash: 1ca6806e9f62696760dac4321fce849b
+configured_endpoints: 106
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/mux%2Fmux-d4d7fca3b738848f0ecb2658b7a8ee82f51886dae8014266671954b980f5fdac.yml
+openapi_spec_hash: 0db43f6551ec879686631abbc738c9b4
+config_hash: 82eb9b770c0e6a5db21fab2794a26a69

.tool-versions

@@ -1,2 +1,2 @@
-nodejs 18.17.0
+nodejs 22
 yarn 1.22.22

CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 12.0.0 (2025-07-02)
+
+Full Changelog: [v11.1.0...v12.0.0](https://github.com/muxinc/mux-node-sdk/compare/v11.1.0...v12.0.0)
+
+### Features
+
+* Expose methods for playback, images, captions, and transcripts
+* Expose MCP server in build
+* Add live stream metadata ([#351](https://github.com/muxinc/mux-node-sdk/issues/351)) ([4bb8e63](https://github.com/muxinc/mux-node-sdk/commit/4bb8e63a3a45330fd1a414148665796750d58eb1))
+* add new copy_overlays asset option ([#355](https://github.com/muxinc/mux-node-sdk/issues/355)) ([7c24f4a](https://github.com/muxinc/mux-node-sdk/commit/7c24f4a9f350568ee1a1dc8c4df54b1e4efe857d))
+* Add progress API fields to the asset model ([#328](https://github.com/muxinc/mux-node-sdk/issues/328)) ([0137bee](https://github.com/muxinc/mux-node-sdk/commit/0137bee04847d310dd74f957de110dda37c28891))
+* **api:** expose playback APIs ([8609c47](https://github.com/muxinc/mux-node-sdk/commit/8609c471e8fbfccc2a34a4e33de23fdd9e76f7ca))
+* **client:** add support for endpoint-specific base URLs ([e3f4bdc](https://github.com/muxinc/mux-node-sdk/commit/e3f4bdca804a846b4a87dac8c04fac26dce6798d))
+* **mcp:** fallback for void-typed methods ([9a9f95f](https://github.com/muxinc/mux-node-sdk/commit/9a9f95fb407f45125a4dbd052852f955f06e5115))
+* **mcp:** implement support for binary responses ([58d6395](https://github.com/muxinc/mux-node-sdk/commit/58d6395935e9a62463578a8c56fd861ef1bc258c))
+* **mcp:** include http information in tools ([24bfa89](https://github.com/muxinc/mux-node-sdk/commit/24bfa892c33d92c2ef84e5b400376f9edb979db6))
+* **mcp:** set X-Stainless-MCP header ([3fc5387](https://github.com/muxinc/mux-node-sdk/commit/3fc53874c819871245e6f8fe32ff4922d0d9683b))
+
+
+### Bug Fixes
+
+* **ci:** release-doctor — report correct token name ([828e709](https://github.com/muxinc/mux-node-sdk/commit/828e7097c6ccc20296d02693664ec7021b835c50))
+* **client:** correct webhooks types ([1c7a3f2](https://github.com/muxinc/mux-node-sdk/commit/1c7a3f27cf9747801429e19d450f1103ff649599))
+* **mcp:** fix cursor schema transformation issue with recursive references ([f02fd01](https://github.com/muxinc/mux-node-sdk/commit/f02fd01050ad69d37110a9f7c5e2e0d4c31775ba))
+* **mcp:** include description in dynamic tool search ([784bb2d](https://github.com/muxinc/mux-node-sdk/commit/784bb2dc1459f2a2066a374281a8a9636d688cb7))
+* publish script — handle NPM errors correctly ([877dd7a](https://github.com/muxinc/mux-node-sdk/commit/877dd7afa69cc0fb4c9105c5bbacd4e0a966aa56))
+
+
+### Chores
+
+* **api:** mark some methods as deprecated ([217c45e](https://github.com/muxinc/mux-node-sdk/commit/217c45e22fd03fb70bcb85c9abf2a0396eed9fe9))
+* **api:** remove webhooks from mcp ([f994bab](https://github.com/muxinc/mux-node-sdk/commit/f994bab88e16aaa5cfb83e58e124fbfff7e25ee3))
+* bump node to 22 in tool-versions ([f80b9be](https://github.com/muxinc/mux-node-sdk/commit/f80b9be030460d3808f3ffa4b2c573e280b7f6b4))
+* **ci:** enable for pull requests ([5c8229d](https://github.com/muxinc/mux-node-sdk/commit/5c8229dc453dc76d98c6786a0b1b39bd4385699d))
+* **ci:** only run for pushes and fork pull requests ([e2d4018](https://github.com/muxinc/mux-node-sdk/commit/e2d40187fdec6354f4ebb0160c352cad8b3c3b25))
+* configure new SDK language ([a4e9260](https://github.com/muxinc/mux-node-sdk/commit/a4e9260a4c79340fa81a77fdf98d16f373f5f1c1))
+* **docs:** grammar improvements ([9735730](https://github.com/muxinc/mux-node-sdk/commit/973573020303420bf493e5cb96a9fa9707a23c76))
+* **docs:** use top-level-await in example snippets ([20bf891](https://github.com/muxinc/mux-node-sdk/commit/20bf8915251e6cb3a6154f476de1a4198043cc6a))
+* improve docs for MCP servers ([252617d](https://github.com/muxinc/mux-node-sdk/commit/252617d0a4d44f5a84a4f16a082ec36bfc380208))
+* improve publish-npm script --latest tag logic ([ac97f0b](https://github.com/muxinc/mux-node-sdk/commit/ac97f0baca1d2feb0446b036538b7855ebaa0700))
+* **internal:** make base APIResource abstract ([d8287a6](https://github.com/muxinc/mux-node-sdk/commit/d8287a6f16341d3dd7e8619f85275d5b124e8c51))
+* **mcp:** provides high-level initMcpServer function and exports known clients ([ff89d71](https://github.com/muxinc/mux-node-sdk/commit/ff89d718e02f7b0992ef4f05752dbab01dcf0c12))
+* **mcp:** remove duplicate assignment ([cec01d6](https://github.com/muxinc/mux-node-sdk/commit/cec01d63d581bb35cc0588150ed3f3c7ff513b94))
+* update mcp package name ([3269450](https://github.com/muxinc/mux-node-sdk/commit/3269450a5a1eb57f791d93e90e7c7f098e17ff5c))
+* upgrade node in upload step ([#354](https://github.com/muxinc/mux-node-sdk/issues/354)) ([5873d7b](https://github.com/muxinc/mux-node-sdk/commit/5873d7bd5f855208b163f90c933f4bec8617e0d4))
+
+
+### Documentation
+
+* **pagination:** improve naming ([289ee67](https://github.com/muxinc/mux-node-sdk/commit/289ee67158efa899084ffe3576c7725111014be7))
+
+
+### Refactors
+
+* **types:** replace Record with mapped types ([8d7ea9c](https://github.com/muxinc/mux-node-sdk/commit/8d7ea9c1ffe3f481a70b8e883d809fd2697500e0))
+
 ## 11.1.0 (2025-05-09)
 
 Full Changelog: [v11.0.2...v11.1.0](https://github.com/muxinc/mux-node-sdk/compare/v11.0.2...v11.1.0)

README.md

@@ -23,21 +23,14 @@ The full API of this library can be found in [api.md](api.md).
 ```js
 import Mux from '@mux/mux-node';
 
-const client = new Mux({
-  tokenId: process.env['MUX_TOKEN_ID'], // This is the default and can be omitted
-  tokenSecret: process.env['MUX_TOKEN_SECRET'], // This is the default and can be omitted
-});
-
-async function main() {
-  const asset = await client.video.assets.create({
-    inputs: [{ url: 'https://storage.googleapis.com/muxdemofiles/mux-video-intro.mp4' }],
-    playback_policies: ['public'],
-  });
+const client = new Mux();
 
-  console.log(asset.id);
-}
+const asset = await client.video.assets.create({
+  inputs: [{ url: 'https://storage.googleapis.com/muxdemofiles/mux-video-intro.mp4' }],
+  playback_policies: ['public'],
+});
 
-main();
+console.log(asset.id);
 ```
 
 ### Request & Response types
@@ -48,20 +41,13 @@ This library includes TypeScript definitions for all request params and response
 ```ts
 import Mux from '@mux/mux-node';
 
-const client = new Mux({
-  tokenId: process.env['MUX_TOKEN_ID'], // This is the default and can be omitted
-  tokenSecret: process.env['MUX_TOKEN_SECRET'], // This is the default and can be omitted
-});
-
-async function main() {
-  const params: Mux.Video.AssetCreateParams = {
-    inputs: [{ url: 'https://storage.googleapis.com/muxdemofiles/mux-video-intro.mp4' }],
-    playback_policies: ['public'],
-  };
-  const asset: Mux.Video.Asset = await client.video.assets.create(params);
-}
+const client = new Mux();
 
-main();
+const params: Mux.Video.AssetCreateParams = {
+  inputs: [{ url: 'https://storage.googleapis.com/muxdemofiles/mux-video-intro.mp4' }],
+  playback_policies: ['public'],
+};
+const asset: Mux.Video.Asset = await client.video.assets.create(params);
 ```
 
 Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
@@ -283,21 +269,17 @@ a subclass of `APIError` will be thrown:
 
 <!-- prettier-ignore -->
 ```ts
-async function main() {
-  const liveStream = await client.video.liveStreams
-    .create({ playback_policies: ['public'] })
-    .catch(async (err) => {
-      if (err instanceof Mux.APIError) {
-        console.log(err.status); // 400
-        console.log(err.name); // BadRequestError
-        console.log(err.headers); // {server: 'nginx', ...}
-      } else {
-        throw err;
-      }
-    });
-}
-
-main();
+const liveStream = await client.video.liveStreams
+  .create({ playback_policies: ['public'] })
+  .catch(async (err) => {
+    if (err instanceof Mux.APIError) {
+      console.log(err.status); // 400
+      console.log(err.name); // BadRequestError
+      console.log(err.headers); // {server: 'nginx', ...}
+    } else {
+      throw err;
+    }
+  });
 ```
 
 Error codes are as follows:
@@ -361,13 +343,13 @@ List methods in the Mux API are paginated.
 You can use the `for await … of` syntax to iterate through items across all pages:
 
 ```ts
-async function fetchAllVideoDeliveryUsages(params) {
-  const allVideoDeliveryUsages = [];
+async function fetchAllDeliveryReports(params) {
+  const allDeliveryReports = [];
   // Automatically fetches more pages as needed.
   for await (const deliveryReport of client.video.deliveryUsage.list()) {
-    allVideoDeliveryUsages.push(deliveryReport);
+    allDeliveryReports.push(deliveryReport);
   }
-  return allVideoDeliveryUsages;
+  return allDeliveryReports;
 }
 ```
 

SECURITY.md

@@ -16,11 +16,11 @@ before making any information public.
 ## Reporting Non-SDK Related Security Issues
 
 If you encounter security issues that are not directly related to SDKs but pertain to the services
-or products provided by Mux please follow the respective company's security reporting guidelines.
+or products provided by Mux, please follow the respective company's security reporting guidelines.
 
 ### Mux Terms and Policies
 
-Please contact [email protected] for any questions or concerns regarding security of our services.
+Please contact [email protected] for any questions or concerns regarding the security of our services.
 
 ---
 

api.md

@@ -167,6 +167,27 @@ Methods:
 - <code title="get /video/v1/drm-configurations/{DRM_CONFIGURATION_ID}">client.video.drmConfigurations.<a href="./src/resources/video/drm-configurations.ts">retrieve</a>(drmConfigurationId) -> DRMConfiguration</code>
 - <code title="get /video/v1/drm-configurations">client.video.drmConfigurations.<a href="./src/resources/video/drm-configurations.ts">list</a>({ ...params }) -> DRMConfigurationsBasePage</code>
 
+## Playback
+
+Types:
+
+- <code><a href="./src/resources/video/playback.ts">PlaybackStoryboardMetaResponse</a></code>
+- <code><a href="./src/resources/video/playback.ts">PlaybackStoryboardVttResponse</a></code>
+- <code><a href="./src/resources/video/playback.ts">PlaybackTrackResponse</a></code>
+- <code><a href="./src/resources/video/playback.ts">PlaybackTranscriptResponse</a></code>
+
+Methods:
+
+- <code title="get /{PLAYBACK_ID}/animated.{EXTENSION}">client.video.playback.<a href="./src/resources/video/playback.ts">animated</a>(playbackId, extension, { ...params }) -> Response</code>
+- <code title="get /{PLAYBACK_ID}.m3u8">client.video.playback.<a href="./src/resources/video/playback.ts">hls</a>(playbackId, { ...params }) -> Response</code>
+- <code title="get /{PLAYBACK_ID}/{FILENAME}">client.video.playback.<a href="./src/resources/video/playback.ts">staticRendition</a>(playbackId, filename, { ...params }) -> Response</code>
+- <code title="get /{PLAYBACK_ID}/storyboard.{EXTENSION}">client.video.playback.<a href="./src/resources/video/playback.ts">storyboard</a>(playbackId, extension, { ...params }) -> Response</code>
+- <code title="get /{PLAYBACK_ID}/storyboard.json">client.video.playback.<a href="./src/resources/video/playback.ts">storyboardMeta</a>(playbackId, { ...params }) -> string</code>
+- <code title="get /{PLAYBACK_ID}/storyboard.vtt">client.video.playback.<a href="./src/resources/video/playback.ts">storyboardVtt</a>(playbackId, { ...params }) -> string</code>
+- <code title="get /{PLAYBACK_ID}/thumbnail.{EXTENSION}">client.video.playback.<a href="./src/resources/video/playback.ts">thumbnail</a>(playbackId, extension, { ...params }) -> Response</code>
+- <code title="get /{PLAYBACK_ID}/text/{TRACK_ID}.vtt">client.video.playback.<a href="./src/resources/video/playback.ts">track</a>(playbackId, trackId, { ...params }) -> string</code>
+- <code title="get /{PLAYBACK_ID}/text/{TRACK_ID}.txt">client.video.playback.<a href="./src/resources/video/playback.ts">transcript</a>(playbackId, trackId, { ...params }) -> string</code>
+
 # Data
 
 ## Dimensions