Types | RelayRTC Docs

Import

import type { CreateRoomInput, ParticipantPermission, Room } from '@relayrtc/node'
 
const input: CreateRoomInput = { name: 'Team call', maxParticipants: 10 }
const permissions: readonly ParticipantPermission[] = ['room:join', 'audio:publish']
 
function roomLabel(room: Room) {
  return room.name
}

Types are exported from the package root. Validation rules and defaults are listed on each method page. A type describes the shape; the API still validates the request.

JsonValue

A JSON value accepted in metadata or event data.

export type JsonValue = string | number | boolean | null | JsonObject | readonly JsonValue[]

JsonObject

A JSON object with string keys.

export interface JsonObject { readonly [key: string]: JsonValue }

RetryOptions

Retry settings for GET requests. Defaults and bounds are in Request options.

export interface RetryOptions {
  readonly maxAttempts?: number
  readonly initialDelayMs?: number
  readonly maxDelayMs?: number
}

RelayServerOptions

Constructor settings. See RelayServer for defaults and URL rules.

export interface RelayServerOptions {
  readonly apiUrl: string
  readonly apiKey: string
  readonly timeoutMs?: number
  readonly retry?: false | RetryOptions
  readonly maxResponseBytes?: number
  readonly fetch?: typeof globalThis.fetch
}

RequestOptions

Overrides for one request. See Request options.

export interface RequestOptions {
  readonly signal?: AbortSignal
  readonly timeoutMs?: number
  readonly retry?: false
}

ApiContext

The project, environment and scopes of the configured key.

export interface ApiContext {
  readonly apiVersion: string
  readonly projectId: string
  readonly environmentId: string
  readonly keyId: string
  readonly keyType: 'publishable' | 'secret'
  readonly scopes: readonly string[]
}

RoomStatus

The stored lifecycle of a room.

export type RoomStatus = 'created' | 'active' | 'ending' | 'ended' | 'failed'

Room

The REST room record. This is different from a browser Room object.

export interface Room {
  readonly id: string
  readonly projectId: string
  readonly environmentId: string
  readonly name: string
  readonly metadata: JsonObject
  readonly status: RoomStatus
  readonly maxParticipants: number
  readonly createdAt: string
  readonly startedAt: string | null
  readonly endedAt: string | null
}

CursorPage

A page of rooms or participants. When pageInfo.hasNextPage is true, pass pageInfo.endCursor as cursor in the next request.

export interface CursorPage<T> {
  readonly nodes: readonly T[]
  readonly pageInfo: { readonly endCursor: string | null; readonly hasNextPage: boolean }
}

CreateRoomInput

The body for rooms.create.

export interface CreateRoomInput {
  readonly name: string
  readonly metadata?: JsonObject
  readonly maxParticipants?: number
}

ListRoomsQuery

Room list filters and cursor pagination.

export interface ListRoomsQuery {
  readonly cursor?: string
  readonly limit?: number
  readonly status?: RoomStatus
}

RuntimeOperation

The status of asynchronous runtime cleanup.

export interface RuntimeOperation {
  readonly id: string
  readonly kind: string
  readonly status: 'pending' | 'running' | 'failed' | 'completed'
  readonly attempts: number
  readonly lastError: string | null
  readonly completedAt: string | null
  readonly [key: string]: unknown
}

CleanupResult

A completed cleanup or a pending operation returned by rooms.end and participants.remove.

export type CleanupResult =
  | { readonly status: 'completed'; readonly httpStatus: 204 }
  | { readonly status: 'pending'; readonly httpStatus: 202; readonly operation: RuntimeOperation }

ParticipantPermission

Capabilities granted by a participant token.

export type ParticipantPermission = typeof participantPermissions[number]

CreateParticipantTokenInput

Participant identity, token lifetime and permissions.

export interface CreateParticipantTokenInput {
  readonly participantName: string
  readonly permissions?: readonly ParticipantPermission[]
  readonly metadata?: JsonObject
  readonly ttlSeconds?: number
}

ParticipantToken

A newly issued participant token and its identity.

export interface ParticipantToken {
  readonly token: string
  readonly participantId: string
  readonly tokenId: string
  readonly expiresAt: string
}

Participant

A participant record returned by room participant endpoints.

export interface Participant {
  readonly id: string
  readonly roomId: string
  readonly externalId: string | null
  readonly name: string
  readonly metadata: JsonObject
  readonly role: string
  readonly joinedAt: string
  readonly leftAt: string | null
}

ListParticipantsQuery

Participant list filters and cursor pagination.

export interface ListParticipantsQuery {
  readonly cursor?: string
  readonly limit?: number
  readonly status?: 'active' | 'left'
}

CreateTurnCredentialsInput

Optional allocation scope. Provide roomId and sessionId together.

export type CreateTurnCredentialsInput =
  | { readonly roomId: string; readonly sessionId: string }
  | { readonly roomId?: never; readonly sessionId?: never }

TurnCredentials

Short-lived ICE configuration for TURN.

export interface TurnCredentials {
  readonly expiresAt: string
  readonly username: string
  readonly ttlSeconds: number
  readonly iceServers: readonly {
    readonly urls: readonly string[]
    readonly username?: string
    readonly credential?: string
    readonly credentialType?: 'password'
  }[]
}

WebhookEventType

An event that a webhook endpoint can subscribe to.

export type WebhookEventType = typeof webhookEventTypes[number]

WebhookEndpointStatus

Whether new deliveries can be sent.

export type WebhookEndpointStatus = 'enabled' | 'disabled'

WebhookDeliveryStatus

The current delivery state.

export type WebhookDeliveryStatus = 'pending' | 'delivering' | 'succeeded' | 'failed' | 'cancelled'

WebhookScopeQuery

Optional project and environment scope. It must match the secret key.

export interface WebhookScopeQuery {
  readonly projectId?: string
  readonly environmentId?: string
}

OffsetQuery

Scope and offset pagination for webhook endpoint lists.

export interface OffsetQuery extends WebhookScopeQuery {
  readonly limit?: number
  readonly offset?: number
}

OffsetPagination

Offset pagination metadata.

export interface OffsetPagination {
  readonly limit: number
  readonly offset: number
  readonly total: number
}

CreateWebhookInput

The settings for a new receiver.

export interface CreateWebhookInput {
  readonly url: string
  readonly eventTypes: readonly WebhookEventType[]
  readonly status?: WebhookEndpointStatus
}

UpdateWebhookInput

The settings to replace on an existing receiver.

export interface UpdateWebhookInput {
  readonly url?: string
  readonly eventTypes?: readonly WebhookEventType[]
  readonly status?: WebhookEndpointStatus
}

WebhookEndpoint

A receiver record without its signing secret.

export interface WebhookEndpoint {
  readonly id: string
  readonly projectId: string
  readonly environmentId: string
  readonly url: string
  readonly eventTypes: readonly WebhookEventType[]
  readonly status: WebhookEndpointStatus
  readonly signingSecretVersion: number
  readonly signingSecretRotatedAt: string
  readonly createdAt: string
  readonly updatedAt: string
}

RevealedWebhookEndpoint

A receiver returned by creation or rotation, including a signing secret to save securely.

export interface RevealedWebhookEndpoint extends WebhookEndpoint {
  readonly signingSecret: string
  readonly rotationPolicy: 'immediate replacement'
}

WebhookEndpointList

A page of configured receivers.

export interface WebhookEndpointList {
  readonly endpoints: readonly WebhookEndpoint[]
  readonly pagination: OffsetPagination
}

WebhookEvent

The event envelope sent as JSON to a receiver.

export interface WebhookEvent {
  readonly id: string
  readonly type: WebhookEventType
  readonly projectId: string
  readonly environmentId: string
  readonly occurredAt: string
  readonly data: JsonObject
}

WebhookDelivery

A delivery record and its latest outcome.

export interface WebhookDelivery {
  readonly id: string
  readonly endpointId: string
  readonly eventId: string
  readonly projectId: string
  readonly environmentId: string
  readonly url: string
  readonly status: WebhookDeliveryStatus
  readonly attemptCount: number
  readonly runAttemptCount: number
  readonly replayCount: number
  readonly lastError: string | null
  readonly nextAttemptAt: string | null
  readonly deliveredAt: string | null
  readonly runStartedAt: string
  readonly createdAt: string
  readonly updatedAt: string
}

WebhookDeliveryAttempt

One HTTP attempt, including its result.

export interface WebhookDeliveryAttempt {
  readonly id: string
  readonly attemptNumber: number
  readonly replayCount: number
  readonly status: 'started' | 'succeeded' | 'failed' | 'abandoned'
  readonly signingSecretVersion: number
  readonly signatureTimestamp: number
  readonly httpStatus: number | null
  readonly errorCode: string | null
  readonly startedAt: string
  readonly finishedAt: string | null
}

WebhookDeliveryDetail

The delivery, event, original JSON body and attempt history.

export interface WebhookDeliveryDetail extends WebhookDelivery {
  readonly event: WebhookEvent
  readonly rawBody: string
  readonly attempts: readonly WebhookDeliveryAttempt[]
}

WebhookDeliveryList

A page of deliveries.

export interface WebhookDeliveryList {
  readonly deliveries: readonly WebhookDelivery[]
  readonly pagination: OffsetPagination
}

ListWebhookDeliveriesQuery

Filters and pagination for delivery logs.

export interface ListWebhookDeliveriesQuery extends OffsetQuery {
  readonly status?: WebhookDeliveryStatus
}

ReplayWebhookDeliveryInput

The current replay counter required for an explicit replay.

export interface ReplayWebhookDeliveryInput { readonly expectedReplayCount: number }

WebhookSignatureContract

The signature headers and delivery policy reported by the API.

export interface WebhookSignatureContract {
  readonly version: 'v1'
  readonly algorithm: 'HMAC-SHA256'
  readonly signatureHeader: string
  readonly deliveryIdHeader: string
  readonly replayCountHeader: string
  readonly secretVersionHeader: string
  readonly signedContent: string
  readonly signatureFormat: string
  readonly secretEncoding: string
  readonly toleranceSeconds: number
  readonly attemptsPerRun: number
  readonly maximumExplicitReplays: number
  readonly backoffSeconds: readonly number[]
  readonly maximumRunAgeDays: number
  readonly terminalRetentionDays: number
  readonly [key: string]: string | number | readonly number[]
}

UsageCategory

The usage category to request.

export type UsageCategory = 'all' | 'rooms' | 'participants' | 'sfu' | 'turn' | 'signaling' | 'screen-share'

UsageRange

A preset reporting window.

export type UsageRange = '24h' | '7d' | '14d' | '30d'

UsageQuery

A preset or explicit usage window. Do not combine range with startedAt and endedAt.

UsageWindowQuery is an internal helper used by this public type:

type UsageWindowQuery =
  | { readonly range?: UsageRange; readonly startedAt?: never; readonly endedAt?: never }
  | { readonly range?: never; readonly startedAt: string; readonly endedAt: string }

export type UsageQuery = UsageWindowQuery & {
  readonly projectId?: string
  readonly environmentId?: string
  readonly granularity?: 'hour' | 'day'
  readonly category?: UsageCategory
}

UsageMetric

A supported metric identifier.

export type UsageMetric =
  | 'participantSeconds' | 'participantMinutesDerived' | 'audioParticipantSeconds'
  | 'videoParticipantSeconds' | 'screenShareSeconds' | 'screenShareIngressBytes'
  | 'screenShareEgressBytes' | 'sfuIngressBytes' | 'sfuEgressBytes' | 'turnIngressBytes'
  | 'turnEgressBytes' | 'turnRelaySeconds' | 'turnSessions' | 'roomsCreated' | 'roomsStarted'
  | 'roomSeconds' | 'averageConcurrentParticipants' | 'peakConcurrentParticipants'
  | 'peakConcurrentRooms' | 'signalingConnections' | 'signalingConnectionSeconds'
  | 'signalingMessagesIn' | 'signalingMessagesOut'

UsageMetrics

All usage metric values.

export type UsageMetrics = Readonly<Partial<Record<UsageMetric, number>>>

UsageMetricDefinition

The unit and meaning of one usage metric.

export interface UsageMetricDefinition {
  readonly unit: 'seconds' | 'minutes' | 'bytes' | 'count' | 'participants'
  readonly aggregation: 'sum' | 'union_seconds' | 'count' | 'peak' | 'time_weighted_average' | 'derived' | 'gauge'
  readonly integer: boolean
  readonly definition: string
  readonly source: string
}

UsageResponse

Scoped usage totals, buckets and data quality. See Usage schema.

export interface UsageResponse {
  readonly scope: { readonly organizationId: string; readonly projectId: string; readonly environmentId: string }
  readonly category: UsageCategory
  readonly window: {
    readonly range: UsageRange | 'custom'
    readonly startedAt: string
    readonly endedAt: string
    readonly timezone: 'UTC'
    readonly endExclusive: true
  }
  readonly bucketDefinition: {
    readonly granularity: 'hour' | 'day'
    readonly alignment: 'UTC calendar boundaries'
    readonly partialEdges: 'clipped to requested window'
    readonly durations: 'lifecycle intervals clipped to each bucket'
    readonly events: 'attributed to occurrence time'
  }
  readonly metricDefinitions: Readonly<Partial<Record<UsageMetric, UsageMetricDefinition>>>
  readonly summary: UsageMetrics
  readonly buckets: readonly { readonly startedAt: string; readonly endedAt: string; readonly metrics: UsageMetrics }[]
  readonly dataQuality: {
    readonly sessionHistory: 'complete' | 'partial'
    readonly messageHistory: 'complete' | 'partial'
    readonly turnTraffic: 'unavailable' | 'partial' | 'authoritative'
    readonly mediaDurations: 'observation_time'
  }
}

Webhook verification types

export type WebhookHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>
 
export interface WebhookVerificationOptions {
  readonly now?: Date
  readonly toleranceSeconds?: number
}

See verifyWebhookRequest for raw body requirements and timestamp validation.

RelayApiErrorOptions

export interface RelayApiErrorOptions {
  readonly status?: number | null
  readonly requestId?: string | null
  readonly retryable?: boolean
}

See RelayApiError.