videosdk/
lib.rs

1//! Rust server SDK for the [VideoSDK](https://videosdk.live) v2 REST APIs.
2//!
3//! # Getting started
4//!
5//! Construct a [`Client`] from your project credentials. It reads
6//! `VIDEOSDK_API_KEY` and `VIDEOSDK_SECRET` from the environment when they are
7//! not passed explicitly.
8//!
9//! ```no_run
10//! # #[tokio::main]
11//! # async fn main() -> Result<(), videosdk::Error> {
12//! let client = videosdk::Client::builder()
13//!     .api_key("my-key")
14//!     .secret("my-secret")
15//!     .build()?;
16//! # Ok(())
17//! # }
18//! ```
19//!
20//! # Authentication
21//!
22//! The client mints a short-lived HS256 JWT from your key and secret, attaches
23//! it to every request, and refreshes it before it expires. Signing happens
24//! locally — nothing is sent anywhere to authenticate. You never construct a
25//! token or set a header yourself.
26//!
27//! To mint a token for a *participant* — to hand to a client-side SDK — use
28//! [`Client::access_token`]:
29//!
30//! ```no_run
31//! # use videosdk::Grant;
32//! # use std::time::Duration;
33//! # fn main() -> Result<(), videosdk::Error> {
34//! # let client = videosdk::Client::new()?;
35//! let token = client
36//!     .access_token()?
37//!     .set_participant("participant-1")
38//!     .grant(Grant::AllowJoin)
39//!     .for_room("room-1")
40//!     .expires_in(Duration::from_secs(2 * 60 * 60))
41//!     .to_jwt()?;
42//! # Ok(())
43//! # }
44//! ```
45//!
46//! # Optional parameters
47//!
48//! Request parameters are plain structs whose optional fields are `Option<T>`.
49//! Build them with struct-update syntax:
50//!
51//! ```ignore
52//! let params = ListRoomsParams {
53//!     page: Some(2),
54//!     ..Default::default()
55//! };
56//! ```
57//!
58//! # Errors
59//!
60//! Every call returns [`Result<T>`]. Match on [`Error`], or use the predicates:
61//!
62//! ```no_run
63//! # async fn f(client: &videosdk::Client) {
64//! # let result: videosdk::Result<serde_json::Value> = Err(videosdk::Error::Validation("x".into()));
65//! match result {
66//!     Ok(room) => println!("{room}"),
67//!     Err(err) if err.is_not_found() => println!("no such room"),
68//!     Err(err) => eprintln!("failed: {err}"),
69//! }
70//! # }
71//! ```
72//!
73//! # Retries
74//!
75//! Requests are retried up to [`ClientBuilder::max_retries`] times (2 by
76//! default) with exponential backoff and jitter. A 429 is always retried, and
77//! honors the server's `Retry-After`. Network errors, timeouts and 5xx
78//! responses are retried only for idempotent methods, so a `POST` is never
79//! replayed.
80//!
81//! # Pagination
82//!
83//! List endpoints return a [`Page`]. Walk it by hand with [`Page::next_page`],
84//! or stream every item across every page with [`Page::into_stream`].
85
86#![warn(missing_docs)]
87#![warn(clippy::all)]
88#![forbid(unsafe_code)]
89
90mod builder;
91mod client;
92mod common;
93mod error;
94mod pagination;
95mod query;
96mod resources;
97mod token;
98
99#[cfg(test)]
100mod decode_tests;
101#[cfg(test)]
102mod http_tests;
103#[cfg(test)]
104mod test_support;
105
106pub use builder::{ClientBuilder, TokenOptions};
107pub use client::{Api, Client, Expect, RawRequest, DEFAULT_BASE_URL, VERSION};
108pub use common::{
109    CompositionConfig, CompositionQuality, LayoutConfig, LayoutPriority, LayoutType,
110    MessageResponse, OnFailureConfig, Orientation, ParticipantFileFormat, RecordingFile,
111    RecordingFileFormat, Region, ResourceLinks, SummaryConfig, Theme, TrackFileFormat, TrackKind,
112    TranscriptionConfig, WebhookDelivery, WebhookDeliverySummary,
113};
114pub use error::{ApiError, Error, ErrorKind, Result};
115pub use pagination::{ListParams, Page, PageInfo};
116pub use token::{
117    decode_token, generate_token, parse_expires_in, verify_token, AccessTokenBuilder,
118    GenerateTokenParams, Grant, TokenClaims, DEFAULT_TOKEN_TTL,
119};
120
121pub use resources::agents::{
122    AgentComputeProfile, AgentDeployment, AgentDeploymentResource, AgentDeploymentVersion,
123    AgentImage, AgentInitConfig, AgentLogEntry, AgentRoomOptions, AgentScaling, AgentsResource,
124    DeployAgentParams, DeployImage, DeployedAgent, DispatchAgentParams, DispatchResult,
125    GeneralDispatchAgentParams, ListDeploymentLogsParams, ListDeploymentsParams,
126};
127pub use resources::alert_rules::{
128    AbsentDataAlert, AlertConditionOperator, AlertDomain, AlertMatchType, AlertReduceTo, AlertRule,
129    AlertRuleCondition, AlertRuleConfig, AlertRuleEvaluation, AlertRuleFilter, AlertRuleGroupBy,
130    AlertRuleHaving, AlertRuleQuery, AlertRuleStatus, AlertRulesResource, AlertSeverity,
131    CreateAlertRuleParams, ListAlertRulesParams, UpdateAlertRuleParams,
132};
133pub use resources::batch_calls::{
134    BatchCall, BatchCallCancelMode, BatchCallRecord, BatchCallRecordsResource,
135    BatchCallRetryConfig, BatchCallRetryStatus, BatchCallStats, BatchCallStatus, BatchCallTiming,
136    BatchCallWebhookConfig, BatchCallWebhookEvent, BatchCallsResource, CreateBatchCallParams,
137    DeleteRecordsResult, ExportBatchCallRecordsParams, ListBatchCallRecordsParams,
138    ListBatchCallsParams, UpdateBatchCallParams, UpdateBatchCallRecordParams,
139    UploadBatchCallParams,
140};
141pub use resources::connectors::{
142    Connector, ConnectorProvider, ConnectorsResource, CreateConnectorParams,
143};
144pub use resources::egress::{Composition, CompositionLayout, EgressHandle, EgressType, StopTarget};
145pub use resources::hls::{
146    HlsCaptureFormat, HlsCaptureParams, HlsCaptureResult, HlsListParams, HlsResource,
147    HlsStartParams, HlsStream,
148};
149pub use resources::ingress::{
150    CreateSocketIngressParams, CreateWhepParams, CreateWhipParams, SocketIngress,
151    SocketIngressAgent, SocketIngressResource, WhepPlayback, WhepResource, WhepSource, WhipIngress,
152    WhipResource,
153};
154pub use resources::participants::ParticipantsResource;
155pub use resources::recordings::{
156    CompositeParticipantSelector, CompositeRecording, CompositeRecordingListParams,
157    CompositeRecordingStartParams, CompositeWatermark, IndividualRecording,
158    IndividualRecordingListParams, MergeChannel, MergeChannelEntry, MergeRecording,
159    MergeRecordingCreateParams, MergeRecordingListParams, MergeRecordingResource,
160    MergeRecordingResult, ParticipantRecordingStartParams, Recording, RecordingCompositeResource,
161    RecordingGetParams, RecordingListParams, RecordingParticipantResource, RecordingStartParams,
162    RecordingTrackResource, RecordingsResource, TrackRecordingStartParams,
163};
164pub use resources::resource_pool::{
165    AcquireResourceParams, ComposerType, ListResourcesParams, ReleaseResourceResult, ResourceMode,
166    ResourcePoolResource, ResourceQuality, ResourceStatus, ResourceUnit,
167};
168pub use resources::rooms::{
169    AutoCloseConfig, AutoCloseConfigInput, AutoCloseType, AutoStartConfig, MultiComposition, Room,
170    RoomCreateParams, RoomListParams, RoomValidation, RoomWebhook, RoomWebhookInput, RoomsResource,
171};
172pub use resources::rtmp::{Livestream, RtmpListParams, RtmpResource, RtmpStartParams, RtmpStream};
173pub use resources::sessions::{
174    Participant, ParticipantTimelog, QualityStats, Session, SessionEndParams, SessionListParams,
175    SessionRemoveParticipantParams, SessionStatus, SessionsResource,
176};
177pub use resources::sip::{
178    CreateInboundTrunkParams, CreateOutboundTrunkParams, CreatePhoneNumbersParams,
179    CreateRoutingRuleParams, CreateSipCallParams, CreateSipWebhookParams, InboundTrunkResource,
180    OutboundTrunkResource, PhoneNumberInboundConfig, PhoneNumberInfo, PhoneNumberListParams,
181    PhoneNumberOutboundConfig, PhoneNumberWithGateways, PhoneNumbersResource, RoutingRuleTarget,
182    SipAuth, SipCall, SipCallListParams, SipCallStatus, SipCallsResource, SipDirection,
183    SipIncludeHeaders, SipMediaEncryption, SipRegion, SipResource, SipRoomConfig, SipRoomPrefix,
184    SipRoomType, SipRoutingRule, SipRoutingRuleListParams, SipRoutingRulesResource, SipTransport,
185    SipTrunk, SipTrunkListParams, SipTrunksResource, SipWebhook, SipWebhookEvent,
186    SipWebhookListParams, SipWebhooksResource, SwitchRoomParams, TransferSipCallParams,
187    UpdateInboundTrunkParams, UpdateOutboundTrunkParams, UpdatePhoneNumberGatewayParams,
188    UpdateRoutingRuleParams,
189};
190pub use resources::transcodings::{
191    HlsToMp4Params, ListTranscodingsParams, MeetingRecordingMergeParams, MeetingRecordingRef,
192    MergeTranscodingParams, Transcoding, TranscodingFile, TranscodingStatus, TranscodingStorage,
193    TranscodingTask, TranscodingWatermark, TranscodingsResource,
194};
195pub use resources::transcription::{
196    ListRealtimeTranscriptionsParams, RealtimeSummaryConfig, RealtimeTranscription,
197    RealtimeTranscriptionExtension, RealtimeTranscriptionExtensionConfig,
198    RealtimeTranscriptionResource, StartRealtimeTranscriptionParams, TranscriptionResource,
199};
200
201// Re-exported so callers can name the types used by the escape hatch without
202// depending on the exact `reqwest` and `serde_json` versions themselves.
203pub use reqwest::Method;
204pub use serde_json::Value;
videosdk/lib.rs

videosdk/
lib.rs
