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@betaQuick migration checklist
- Install the beta and build. Fix whatever TypeScript flags from Changed method signatures and Removed APIs.
- 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 inconvertTimestampToDate. This one fails silently - see below. - Never pass a timestamp read from a response back into a request without converting it first.
- If you pass an explicit
baseURL, drop the/videosuffix and any trailing slash. - Replace any
*Enumimport with the plain string it stood for. - If you call
client.streamClient.get/post/put/patch/deleteordoAxiosRequest, move to the generatedclient.api/call.apioperations. - 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);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; // newReading 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 clientThe 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.