Skip to content

chore: improve voip enums definitions #41045

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ggazzo merged 3 commits into from
Jun 24, 2026
+92 −102
Merged

chore: improve voip enums definitions #41045

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7e7ff5e
chore: improve voip enums definitions
pierre-lehnen-rc Jun 22, 2026
7f558ce
as const
pierre-lehnen-rc Jun 23, 2026
1808a30
Merge branch 'develop' into chore/voip-enum-types
pierre-lehnen-rc Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 59 additions & 46 deletions packages/media-signaling/src/definition/call/IClientMediaCall.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,34 +14,39 @@ export const callFeatureList = ['audio', 'screen-share', 'transfer', 'hold'] as

export type CallFeature = (typeof callFeatureList)[number];

export type CallState =
| 'none' // trying to call with no idea if it'll reach anyone
| 'ringing' // call has been acknoledged by the callee's agent, but no response about them accepting it or not
| 'accepted' // call has been accepted and the webrtc offer is being exchanged
| 'active' // webrtc connection has been established
| 'renegotiating' // a webrtc connection had been established before, but a new one is being negotiated
| 'hangup'; // call is over

// Changes to this list must be reflected on the enum for clientMediaSignalHangupSchema too
export type CallHangupReason =
| 'normal' // User explicitly hanged up
| 'remote' // The client was told the call is over
| 'rejected' // The callee rejected the call
| 'unavailable' // The actor is not available
| 'transfer' // one of the users requested the other be transferred to someone else
| 'not-answered' // max ringing duration was reached with no answer from the other user
| 'timeout-local-track' // Timeout waiting for the local audio track
| 'timeout-remote-sdp' // Timeout waiting for the remote SDP
| 'timeout-local-sdp' // Timeout while generating the local SDP + waiting for ICE Gathering
| 'timeout-activation' // Timeout connecting to the negotiated session
| 'timeout' // The call state hasn't progressed for too long
| 'signaling-error' // Hanging up because of an error during the signal processing
| 'service-error' // Hanging up because of an error setting up the service connection
| 'media-error' // Hanging up because of an error setting up the media connection
| 'input-error' // Something wrong with the audio input track on the client
| 'error' // Hanging up because of an unidentified error
| 'unknown' // One of the call's signed users reported they don't know this call
| 'another-client'; // One of the call's users requested a hangup from a different client session than the one where the call is happening
export const callStateList = [
'none', // trying to call with no idea if it'll reach anyone
'ringing', // call has been acknoledged by the callee's agent, but no response about them accepting it or not
'accepted', // call has been accepted and the webrtc offer is being exchanged
'active', // webrtc connection has been established
'renegotiating', // a webrtc connection had been established before, but a new one is being negotiated
'hangup', // call is over
] as const;

export type CallState = (typeof callStateList)[number];
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.

Comment thread
coderabbitai[bot] marked this conversation as resolved.
export const callHangupReasonList = [
'normal', // User explicitly hanged up
'remote', // The client was told the call is over
'rejected', // The callee rejected the call
'unavailable', // The actor is not available
'transfer', // one of the users requested the other be transferred to someone else
'not-answered', // max ringing duration was reached with no answer from the other user
'timeout-local-track', // Timeout waiting for the local audio track
'timeout-remote-sdp', // Timeout waiting for the remote SDP
'timeout-local-sdp', // Timeout while generating the local SDP + waiting for ICE Gathering
'timeout-activation', // Timeout connecting to the negotiated session
'timeout', // The call state hasn't progressed for too long
'signaling-error', // Hanging up because of an error during the signal processing
'service-error', // Hanging up because of an error setting up the service connection
'media-error', // Hanging up because of an error setting up the media connection
'input-error', // Something wrong with the audio input track on the client
'error', // Hanging up because of an unidentified error
'unknown', // One of the call's signed users reported they don't know this call
'another-client', // One of the call's users requested a hangup from a different client session than the one where the call is happening
] as const;

export type CallHangupReason = (typeof callHangupReasonList)[number];

export const callAnswerList = [
'accept', // actor accepts the call
Expand All @@ -52,24 +57,32 @@ export const callAnswerList = [

export type CallAnswer = (typeof callAnswerList)[number];

export type CallNotification =
| 'accepted' // notify that the call has been accepted by both actors
| 'active' // notify that call activity was confirmed
| 'hangup' // notify that the call is over;
| 'trying'; // notify that the other client is connecting but still need more time

export type CallRejectedReason =
| 'invalid-call-id' // the call id can't be used for a new call
| 'invalid-contract-id' // this specific contract can't request this call
| 'existing-call-id' // the call already exists with a different callee or contract
| 'already-requested' // the request is valid, but a call matching its params is already underway
| 'unsupported' // no matching supported services between actors
| 'unavailable' // the callee is unavailable
| 'busy' // the actor who requested the call is supposedly busy
| 'invalid-call-params' // something is wrong with the params (eg. no valid route between caller and callee)
| 'forbidden'; // one of the actors on the call doesn't have permission for it

export type CallFlag = 'internal' | 'create-data-channel';
export const callNotificationList = [
'accepted', // notify that the call has been accepted by both actors
'active', // notify that call activity was confirmed
'hangup', // notify that the call is over;
'trying', // notify that the other client is connecting but still need more time
] as const;

export type CallNotification = (typeof callNotificationList)[number];

export const callRejectedReasonList = [
'invalid-call-id', // the call id can't be used for a new call
'invalid-contract-id', // this specific contract can't request this call
'existing-call-id', // the call already exists with a different callee or contract
'already-requested', // the request is valid, but a call matching its params is already underway
'unsupported', // no matching supported services between actors
'unavailable', // the callee is unavailable
'busy', // the actor who requested the call is supposedly busy
'invalid-call-params', // something is wrong with the params (eg. no valid route between caller and callee)
'forbidden', // one of the actors on the call doesn't have permission for it
] as const;

export type CallRejectedReason = (typeof callRejectedReasonList)[number];

export const callFlagList = ['internal', 'create-data-channel'];

export type CallFlag = (typeof callFlagList)[number];

export interface IClientMediaCall {
callId: string;
Expand Down
44 changes: 25 additions & 19 deletions packages/media-signaling/src/definition/client.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,28 @@
export type ClientState =
| 'none' // The client doesn't recognize a specific call id at all
| 'pending' // The call is ringing
| 'accepting' // The client tried to accept the call and is wating for confirmation from the server
| 'waiting-for-track' // The call was accepted, but the client doesn't have a local audio stream yet
| 'waiting-for-offer' // The call was accepted, but the client doesn't have a webrtc offer yet
| 'waiting-for-answer' // The call was accepted and an offer was already sent, but the client doesn't have an answer yet
| 'generating-local-sdp' // The client is generating its first local sdp (offer/answer)
| 'activating' // The WebRTC signaling has reached the stable state, but the connection is not yet active
| 'busy-elsewhere' // The call is happening in a different session/client
| 'active' // The webrtc call was established
| 'renegotiating' // the webrtc call was established but the client is starting a new negotiation
| 'hangup'; // The call is over, or happening in some other client
export const clientStateList = [
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
'none', // The client doesn't recognize a specific call id at all
'pending', // The call is ringing
'accepting', // The client tried to accept the call and is wating for confirmation from the server
'waiting-for-track', // The call was accepted, but the client doesn't have a local audio stream yet
'waiting-for-offer', // The call was accepted, but the client doesn't have a webrtc offer yet
'waiting-for-answer', // The call was accepted and an offer was already sent, but the client doesn't have an answer yet
'generating-local-sdp', // The client is generating its first local sdp (offer/answer)
'activating', // The WebRTC signaling has reached the stable state, but the connection is not yet active
'busy-elsewhere', // The call is happening in a different session/client
'active', // The webrtc call was established
'renegotiating', // the webrtc call was established but the client is starting a new negotiation
'hangup', // The call is over, or happening in some other client
] as const;

export type ClientContractState =
| 'proposed' // we don't know if the contract will be signed
| 'signed' // the server signed this session's contract
| 'pre-signed' // the session that requested a call is assuming it will be signed into it
| 'self-signed' // the call has progressed beyond the signing stage without any signature confirmation
| 'ignored'; // the server signed a contract from a different session
export type ClientState = (typeof clientStateList)[number];
Comment thread
coderabbitai[bot] marked this conversation as resolved.

export const clientContractStateList = [
'proposed', // we don't know if the contract will be signed
'signed', // the server signed this session's contract
'pre-signed', // the session that requested a call is assuming it will be signed into it
'self-signed', // the call has progressed beyond the signing stage without any signature confirmation
'ignored', // the server signed a contract from a different session
] as const;

export type ClientContractState = (typeof clientContractStateList)[number];

export type RandomStringFactory = () => string;
2 changes: 1 addition & 1 deletion packages/media-signaling/src/definition/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@ export * from './call';
export type * from './services';
export type * from './media';
export * from './signals';
export type * from './client';
export * from './client';
export type * from './logger';
22 changes: 2 additions & 20 deletions packages/media-signaling/src/definition/signals/client/hangup.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { JSONSchemaType } from 'ajv';

import type { CallHangupReason } from '../../call';
import { callHangupReasonList, type CallHangupReason } from '../../call';

/** Client is saying they hanged up from a call. The reason specifies if its a clean hangup or an error */
export type ClientMediaSignalHangup = {
Expand Down Expand Up @@ -30,25 +30,7 @@ export const clientMediaSignalHangupSchema: JSONSchemaType<ClientMediaSignalHang
},
reason: {
type: 'string',
enum: [
'normal',
'remote',
'rejected',
'unavailable',
'transfer',
'timeout',
'not-answered',
'timeout-remote-sdp',
'timeout-local-sdp',
'timeout-activation',
'signaling-error',
'service-error',
'media-error',
'input-error',
'error',
'unknown',
'another-client',
],
enum: callHangupReasonList,
nullable: false,
},
},
Expand Down
21 changes: 5 additions & 16 deletions packages/media-signaling/src/definition/signals/client/local-state.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
import type { JSONSchemaType } from 'ajv';

import type { CallState } from '../../call';
import { callStateList, type CallState } from '../../call';
import type { ClientContractState, ClientState } from '../../client';
import { clientContractStateList, clientStateList } from '../../client';

/** Client is sending their local call state */
export type ClientMediaSignalLocalState = {
Expand Down Expand Up @@ -36,24 +37,12 @@ export const clientMediaSignalLocalStateSchema: JSONSchemaType<ClientMediaSignal
},
callState: {
type: 'string',
enum: ['none', 'ringing', 'accepted', 'active', 'renegotiating', 'hangup'],
enum: callStateList,
nullable: false,
},
clientState: {
type: 'string',
enum: [
'none',
'pending',
'accepting',
'waiting-for-offer',
'waiting-for-answer',
'generating-local-sdp',
'activating',
'busy-elsewhere',
'active',
'renegotiating',
'hangup',
],
enum: clientStateList,
nullable: false,
},
serviceStates: {
Expand All @@ -72,7 +61,7 @@ export const clientMediaSignalLocalStateSchema: JSONSchemaType<ClientMediaSignal
},
contractState: {
type: 'string',
enum: ['proposed', 'signed', 'pre-signed', 'self-signed', 'ignored'],
enum: clientContractStateList,
nullable: false,
},
negotiationId: {
Expand Down
Loading