Info:
This is beta documentation for Stream Video JavaScript SDK v2. For the latest stable version, see the latest version (v1).

Upgrade to v2

v2 of the JavaScript client is in beta. This page tracks what you have to change when moving from v1.

The client's coordinator calls are now generated from the OpenAPI spec rather than written by hand. Most method names are unchanged, but a group of methods moved from positional arguments to a single object, the data they return is typed differently, and a few APIs that were deprecated in v1 are removed. One of these changes fails silently - read the dates section even if you read nothing else.

Install the beta

v2 publishes to the beta npm tag. v1 keeps latest, so an unpinned install stays on v1.

yarn add @stream-io/video-client@beta

Quick migration checklist

  1. Install the beta and build. Fix whatever TypeScript flags from Changed method signatures and Removed APIs.
  2. Search for new Date( applied to anything from a response or event - created_at, starts_at, ended_at, live_started_at, joined_at. Wrap those in convertTimestampToDate. This one fails silently - see below.
  3. Never pass a timestamp read from a response back into a request without converting it first.
  4. If you pass an explicit baseURL, drop the /video suffix and any trailing slash.
  5. Replace any *Enum import with the plain string it stood for.
  6. If you call client.streamClient.get/post/put/patch/delete or doAxiosRequest, move to the generated client.api / call.api operations.
  7. If you pass axiosRequestConfig, check it does not try to override the auth or identity parameters - see Request configuration.

Dates are numbers now

Every date the server sends is a unix-nanosecond number (typed TimestampNS) instead of an ISO string. v1 called the /video routes, which send ISO strings; v2 calls the /api/v2/... routes, which send unix-nanosecond numbers - in responses and in WebSocket events alike.

// v1
const startedAt = new Date(call.created_at);

// v2
import { convertTimestampToDate } from "@stream-io/video-client";
const startedAt = convertTimestampToDate(call.created_at);
Warning:

This one does not throw. A nanosecond timestamp is far outside the range Date accepts, so new Date(call.created_at) returns an Invalid Date - and .getTime() on it is NaN, which then spreads through whatever you compute from it. You get a blank timestamp or a NaN duration on screen, with nothing in the console.

TypeScript catches most of it: new Date(timestamp).getTime() and other Date methods are a compile error. It does not catch new Date(timestamp) on its own, or .toLocaleString() and template strings on the result, and plain JavaScript gets no warning at all.

Three helpers are exported for the conversion:

Helper Use it for
convertTimestampToDate(ts) a timestamp off a response or event - returns undefined if absent or invalid
nsToDate(ts) a timestamp you know is present
nowNs() the current time, to compare against a wire timestamp

The same applies to maps of timestamps, such as session.accepted_by, session.rejected_by and session.missed_by: their values are TimestampNS now.

The call state is unaffected. call.state.createdAt, call.state.startsAt and call.state.endedAt are still Date objects - only raw responses and events carry numbers, so there is nothing to wrap there.

Dates you send are still Date

Request fields such as starts_at take a Date (an ISO string also works at runtime). That makes dates not round-trippable: a timestamp read from a response cannot be sent back as-is. TypeScript flags it, because a TimestampNS is not assignable to Date. In plain JavaScript, or through an any, the API rejects the number with a 400 - Time.UnmarshalJSON: input is not a JSON string.

// v2 - compile error in TypeScript, 400 at runtime
await call.update({ starts_at: response.call.starts_at });

// v2 - convert first
import { nsToDate } from "@stream-io/video-client";
await call.update({ starts_at: nsToDate(response.call.starts_at) });

The same goes for date filters: { created_at: { $gte: <number> } } is rejected, so pass a Date or an ISO string.

A few request fields that v1 typed as string, such as CallRequest.starts_at, are typed Date in v2. An ISO string still works at runtime, but TypeScript now flags it.

Base URL no longer takes the /video suffix

The generated client issues absolute paths (/api/v2/video/...), so a base URL ending in /video now produces /video/api/v2/video/...: every request 404s and the WebSocket connection drops.

// v1
new StreamVideoClient({
  apiKey,
  options: { baseURL: "https://my-proxy.example.com/video" },
});

// v2
new StreamVideoClient({
  apiKey,
  options: { baseURL: "https://my-proxy.example.com" },
});

Pass the host only - no /video suffix and no trailing slash. A trailing slash produces //api/v2/..., and those requests fail too.

If you never set baseURL, there is nothing to do.

The base URL is fixed for the life of the client: client.streamClient.setBaseURL() was removed. To switch environments, disconnect the client and create a new one with the new baseURL.

The *Enum exports are gone

Fields that used to have a generated enum object are plain string unions now, so the string itself is the value - and a typo is a compile error rather than a lookup that returns undefined.

// v1
if (settings.audio.noise_cancellation?.mode === NoiseCancellationSettingsModeEnum.AUTO_ON)

// v2
if (settings.audio.noise_cancellation?.mode === "auto-on")

Forty-two of these were removed, covering noise cancellation, recording, transcription, closed captions, RTMP, HLS, encryption, permissions and device push providers. They all follow the same shape: SomethingEnum.SOME_VALUE becomes "some-value".

Query filters are typed

filter_conditions on queryCalls, queryMembers, queryParticipants and queryCallStats is typed against the fields the API can filter on, instead of { [key: string]: any }. Custom fields ("custom.color"), operators ($in, $gte, $exists, $and) and dates keep working. A field the API does not support is now a compile error instead of a request that silently matches nothing.

Responses carry a metadata envelope

Every response is now StreamResponse<T> - your data, plus a metadata field with the response code, rate-limit state and request id.

const response = await call.get();
response.call; // unchanged
response.metadata.rate_limit.rate_limit_remaining; // new

Reading fields off a response needs no change. It only matters if you spread a response into something typed, or assert an exact shape.

Changed method signatures

These methods now take a single object instead of positional arguments. TypeScript flags the old form; plain JavaScript does not, and the request fails or sends the wrong data.

v1 v2
call.startRecording(data, type) call.startRecording({ recording_type, ...data })
call.stopRecording(type) call.stopRecording({ recording_type })
call.blockUser(userId) call.blockUser({ user_id })
call.unblockUser(userId) call.unblockUser({ user_id })
call.reject(reason) call.reject({ reason })
call.getRingState(sessionId) call.getRingState({ call_session_id })
call.stopRTMPBroadcast(name) call.stopRTMPBroadcast({ name })
call.deleteRecording(session, filename) call.deleteRecording({ session, filename })
call.deleteTranscription(session, filename) call.deleteTranscription({ session, filename })
call.getCallReport(sessionId) call.getCallReport({ session_id })
call.getCallStatsMap(params, sessionId) call.getCallStatsMap({ session, ...params })
call.submitFeedback(rating, { reason, custom }) call.submitFeedback({ rating, reason, custom })
call.queryParticipants(data, { limit }) call.queryParticipants({ ...data, limit }) - filter_conditions required
client.addDevice(id, push_provider, push_provider_name, …) client.addDevice({ id, push_provider, push_provider_name, voip_token })
client.addVoipDevice(id, push_provider, push_provider_name, …) client.addVoipDevice({ id, push_provider, push_provider_name })
client.removeDevice(id, userId) client.removeDevice({ id })

Defaults are unchanged: call.startRecording() and call.stopRecording() still use "composite", call.reject() still uses "decline", and call.getRingState() and call.getCallStatsMap() still default to the current session.

// v1
call.startRecording({ recording_external_storage: "my-storage" }, "raw");
call.blockUser("jane");
call.submitFeedback(4, { reason: "Audio dropped" });

// v2
call.startRecording({
  recording_type: "raw",
  recording_external_storage: "my-storage",
});
call.blockUser({ user_id: "jane" });
call.submitFeedback({ rating: 4, reason: "Audio dropped" });

Some arguments are gone because the v2 API no longer accepts them:

v1 v2
call.goLive(data, { notify }) call.goLive(data) - notify is no longer accepted
call.listRecordings(sessionId) call.listRecordings() - no longer filters by session
call.getCallStatsMap({ start_time: "…" }) pass start_time and end_time as Date
client.getDevices(userId) client.getDevices() - server-side targeting removed
client.addDevice(…, userId) the userId argument is gone - server-side targeting removed

Removed APIs

These are gone in v2. TypeScript flags every one of them.

Removed Replacement
logger and logLevel client options logOptions: { default: { level, sink } }
call.publishVideoStream(), call.publishAudioStream(), call.publishScreenShareStream() call.publish(stream, TrackType.VIDEO) (or TrackType.AUDIO, TrackType.SCREEN_SHARE)
secret and allowServerSideConnect client options Use @stream-io/node-sdk for server-side work
call.getCallStats() call.getCallReport()
call.queryRecordings(), call.queryTranscriptions() call.listRecordings(), call.listTranscriptions()
client.streamClient.get(), .post(), .put(), .patch(), .delete() The generated operations on client.api and call.api - see below
client.streamClient.setBaseURL() Pass options.baseURL when creating the client
const client = new StreamVideoClient({
  apiKey,
  user,
  token,
  options: {
    logOptions: { default: { level: "debug" } },
  },
});

The client and authentication guide covers logging in full.

client.streamClient.doAxiosRequest() is still there, but it now resolves to the full Axios response instead of the response body - read .data off it.

Everything the API offers is reachable

Apart from the changes above, the methods you already use are unchanged, and anything the SDK does not surface is on the generated client underneath:

call.goLive(); // curated
call.api.goLive(); // the raw generated operation
client.api.queryCalls(); // anything not promoted onto the client

The api operations send the request and return the response as the API sends it - nothing more. They do not update call.state, and call.api.join() does not connect media. Prefer the curated method wherever one exists.

Request configuration

axiosRequestConfig still applies your own headers, query parameters and Axios options, but it can no longer override the ones the SDK sets itself: user_id, api_key, connection_id, Authorization, stream-auth-type and X-Stream-Client. In v1 a value there replaced the SDK's; in v2 the SDK's value wins.

Call types, call IDs and RTMP broadcast names are now URL-encoded in request paths. In v1 a call ID containing # or ? was cut short and silently addressed a different call; in v2 the API rejects it with a clear error. Valid IDs (a-z, 0-9, _ and -) are unaffected.

What to expect during the beta

Breaking changes land incrementally rather than all at once, so treat this page as the running list and re-read it when you bump. Each entry will name the version it landed in and the change you have to make.

If you hit something that behaves differently and is not listed here, that is worth reporting: an unlisted break is a bug in this page as much as in the SDK.

Staying on v1

v1 is maintained on its own release line and stays on the latest tag. If you are not ready to move, pin @stream-io/video-client@latest and switch this page to v1 with the version picker above.