# Types

Public request, response and configuration types exported by the Node SDK.

## Import

```ts
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.

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

## JsonObject

A JSON object with string keys.

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

## RetryOptions

Retry settings for GET requests. Defaults and bounds are in [Request options](/reference/sdk/server/node/request-options).

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

## RelayServerOptions

Constructor settings. See [RelayServer](/reference/sdk/server/node/RelayServer) for defaults and URL rules.

```ts
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](/reference/sdk/server/node/request-options).

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

## ApiContext

The project, environment and scopes of the configured key.

```ts
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.

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

## Room

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

```ts
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.

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

## CreateRoomInput

The body for rooms.create.

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

## ListRoomsQuery

Room list filters and cursor pagination.

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

## RuntimeOperation

The status of asynchronous runtime cleanup.

```ts
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.

```ts
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.

```ts
export type ParticipantPermission = typeof participantPermissions[number]
```

## CreateParticipantTokenInput

Participant identity, token lifetime and permissions.

```ts
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.

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

## Participant

A participant record returned by room participant endpoints.

```ts
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.

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

## CreateTurnCredentialsInput

Optional allocation scope. Provide roomId and sessionId together.

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

## TurnCredentials

Short-lived ICE configuration for TURN.

```ts
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.

```ts
export type WebhookEventType = typeof webhookEventTypes[number]
```

## WebhookEndpointStatus

Whether new deliveries can be sent.

```ts
export type WebhookEndpointStatus = 'enabled' | 'disabled'
```

## WebhookDeliveryStatus

The current delivery state.

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

## WebhookScopeQuery

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

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

## OffsetQuery

Scope and offset pagination for webhook endpoint lists.

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

## OffsetPagination

Offset pagination metadata.

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

## CreateWebhookInput

The settings for a new receiver.

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

## UpdateWebhookInput

The settings to replace on an existing receiver.

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

## WebhookEndpoint

A receiver record without its signing secret.

```ts
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.

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

## WebhookEndpointList

A page of configured receivers.

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

## WebhookEvent

The event envelope sent as JSON to a receiver.

```ts
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.

```ts
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.

```ts
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.

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

## WebhookDeliveryList

A page of deliveries.

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

## ListWebhookDeliveriesQuery

Filters and pagination for delivery logs.

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

## ReplayWebhookDeliveryInput

The current replay counter required for an explicit replay.

```ts
export interface ReplayWebhookDeliveryInput { readonly expectedReplayCount: number }
```

## WebhookSignatureContract

The signature headers and delivery policy reported by the API.

```ts
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.

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

## UsageRange

A preset reporting window.

```ts
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:

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

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

## UsageMetric

A supported metric identifier.

```ts
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.

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

## UsageMetricDefinition

The unit and meaning of one usage metric.

```ts
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](/reference/api/v1/schemas/usage).

```ts
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

```ts
export type WebhookHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>

export interface WebhookVerificationOptions {
  readonly now?: Date
  readonly toleranceSeconds?: number
}
```

See [verifyWebhookRequest](/reference/sdk/server/node/verifyWebhookRequest) for raw body requirements and timestamp validation.

## RelayApiErrorOptions

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

See [RelayApiError](/reference/sdk/server/node/RelayApiError).