ring

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 6, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package ring provides the main client for interacting with Ring services. It orchestrates authentication, API clients (REST), and event connections.

Package ring provides the main client for interacting with Ring services. This file defines the Client interface for dependency injection and testing.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthenticateRequest

type AuthenticateRequest struct {
	Username string
	Password string
	OTPCode  string
}

AuthenticateRequest contains parameters for Authenticate

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the main client for interacting with Ring services

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient creates a new Ring client

func NewClientWithToken

func NewClientWithToken(accessToken string, opts ...Option) (*Client, error)

NewClientWithToken creates a client with an access token (convenience function)

func (*Client) Apply

func (c *Client) Apply(opts ...Option) error

Apply options to the client.

func (*Client) Authenticate

Authenticate performs full authentication flow with username/password If 2FA is required, it will return a Requires2FAError

func (*Client) Close

func (c *Client) Close() error

Close closes the client and all connections

func (*Client) ConnectEvents

func (c *Client) ConnectEvents(ctx context.Context) (*EventConnection, error)

ConnectEvents establishes a WebSocket connection for receiving events This is a wrapper that calls the internal ConnectEvents method

func (*Client) GetActiveDings

GetActiveDings retrieves currently active dings

func (*Client) GetDevice

func (c *Client) GetDevice(ctx context.Context, req GetDeviceRequest) (ringapimodels.Device, error)

GetDevice retrieves a specific device by ID

func (*Client) GetDeviceHistory

GetDeviceHistory retrieves the history of recordings for a device

func (*Client) GetLastRecordingID

func (c *Client) GetLastRecordingID(ctx context.Context, req GetLastRecordingIDRequest) (int64, error)

GetLastRecordingID retrieves the ID of the most recent recording for a device

func (*Client) GetRecording

GetRecording retrieves a video stream for a recording

func (*Client) ListDevices

func (c *Client) ListDevices(ctx context.Context) (*ringapimodels.DevicesResponse, error)

ListDevices retrieves all devices associated with the account

func (*Client) Listen

func (c *Client) Listen(ctx context.Context, callback ringapimodels.EventCallback) error

Listen listens for events and calls the callback for each event

func (*Client) RefreshToken

RefreshToken refreshes an access token using a refresh token

func (*Client) Request2FACode

func (c *Client) Request2FACode(ctx context.Context, req Request2FACodeRequest) error

Request2FACode requests a 2FA code by attempting authentication

func (*Client) SetInHomeChime

func (c *Client) SetInHomeChime(ctx context.Context, req SetInHomeChimeRequest) error

SetInHomeChime sets in-home chime settings for a doorbell req.Settings can include: "type" (e.g., "Mechanical"), "enabled" (bool), "duration" (int)

func (*Client) SetLights

func (c *Client) SetLights(ctx context.Context, req SetLightsRequest) error

SetLights sets the lights for a device (floodlight cams) req.State can be "on" or "off" req.Duration is optional and specifies how long to keep lights on (in seconds)

func (*Client) SetMotionDetection

func (c *Client) SetMotionDetection(ctx context.Context, req SetMotionDetectionRequest) error

SetMotionDetection sets motion detection for a device

func (*Client) SetVolume

func (c *Client) SetVolume(ctx context.Context, req SetVolumeRequest) error

SetVolume sets the volume for a device

func (*Client) StartRTCStream

func (c *Client) StartRTCStream(ctx context.Context, req StartRTCStreamRequest) (*RTCStream, error)

StartRTCStream starts a WebRTC stream for live video from a device req.SDPOffer is the SDP offer from the caller

func (*Client) StopRTCStream

func (c *Client) StopRTCStream(ctx context.Context, req StopRTCStreamRequest) error

StopRTCStream stops an active RTC stream

func (*Client) TestSound

func (c *Client) TestSound(ctx context.Context, req TestSoundRequest) error

TestSound tests a sound on a chime device req.Kind can be "ding" or "motion"

func (*Client) UpdateDeviceHealth

func (c *Client) UpdateDeviceHealth(ctx context.Context, req UpdateDeviceHealthRequest) (*ringapimodels.DeviceHealth, error)

UpdateDeviceHealth refreshes health data for a device

type ClientInterface

type ClientInterface interface {
	// Authenticate performs full authentication flow with username/password
	Authenticate(ctx context.Context, req AuthenticateRequest) (*ringapimodels.AuthResponse, error)

	// Request2FACode requests a 2FA code by attempting authentication
	Request2FACode(ctx context.Context, req Request2FACodeRequest) error

	// RefreshToken refreshes an access token using a refresh token
	RefreshToken(ctx context.Context, req RefreshTokenRequest) (*ringapimodels.AuthResponse, error)

	// ListDevices retrieves all devices associated with the account
	ListDevices(ctx context.Context) (*ringapimodels.DevicesResponse, error)

	// GetDevice retrieves a specific device by ID
	GetDevice(ctx context.Context, req GetDeviceRequest) (ringapimodels.Device, error)

	// UpdateDeviceHealth refreshes health data for a device
	UpdateDeviceHealth(ctx context.Context, req UpdateDeviceHealthRequest) (*ringapimodels.DeviceHealth, error)

	// SetVolume sets the volume for a device
	SetVolume(ctx context.Context, req SetVolumeRequest) error

	// SetLights sets the lights for a device (floodlight cams)
	SetLights(ctx context.Context, req SetLightsRequest) error

	// SetMotionDetection sets motion detection for a device
	SetMotionDetection(ctx context.Context, req SetMotionDetectionRequest) error

	// TestSound tests a sound on a chime device
	TestSound(ctx context.Context, req TestSoundRequest) error

	// SetInHomeChime sets in-home chime settings for a doorbell
	SetInHomeChime(ctx context.Context, req SetInHomeChimeRequest) error

	// ConnectEvents establishes a WebSocket connection for receiving events
	ConnectEvents(ctx context.Context) (*EventConnection, error)

	// Listen listens for events and calls the callback for each event
	Listen(ctx context.Context, callback ringapimodels.EventCallback) error

	// GetDeviceHistory retrieves the history of recordings for a device
	GetDeviceHistory(ctx context.Context, req GetDeviceHistoryRequest) (*ringapimodels.RecordingHistoryResponse, error)

	// GetActiveDings retrieves currently active dings
	GetActiveDings(ctx context.Context) (*ringapimodels.RecordingHistoryResponse, error)

	// GetRecording retrieves a video stream for a recording
	GetRecording(ctx context.Context, req GetRecordingRequest) (*ringapimodels.VideoStream, error)

	// GetLastRecordingID retrieves the ID of the most recent recording for a device
	GetLastRecordingID(ctx context.Context, req GetLastRecordingIDRequest) (int64, error)

	// StartRTCStream starts a WebRTC stream for live video from a device
	// req.SDPOffer is the SDP offer from the caller
	StartRTCStream(ctx context.Context, req StartRTCStreamRequest) (*RTCStream, error)

	// StopRTCStream stops an active RTC stream
	StopRTCStream(ctx context.Context, req StopRTCStreamRequest) error

	// Close closes the client and all connections
	Close() error
}

ClientInterface defines the interface for the Ring client.

type EventConnection

type EventConnection struct {
	// contains filtered or unexported fields
}

EventConnection represents a WebSocket connection for receiving events

func (*EventConnection) Close

func (ec *EventConnection) Close() error

Close closes the event connection

func (*EventConnection) Receive

func (ec *EventConnection) Receive() (*ringapimodels.Event, error)

Receive receives an event from the connection

type GetDeviceHistoryRequest

type GetDeviceHistoryRequest struct {
	DeviceID string
	Limit    int
	Kind     string
}

GetDeviceHistoryRequest contains parameters for GetDeviceHistory

type GetDeviceRequest

type GetDeviceRequest struct {
	DeviceID string
}

GetDeviceRequest contains parameters for GetDevice

type GetLastRecordingIDRequest

type GetLastRecordingIDRequest struct {
	DeviceID string
}

GetLastRecordingIDRequest contains parameters for GetLastRecordingID

type GetRecordingRequest

type GetRecordingRequest struct {
	RecordingID int64
}

GetRecordingRequest contains parameters for GetRecording

type Option

type Option interface {
	Apply(c *Client) error
}

Option is a function that configures a Client

func WithAccessToken

func WithAccessToken(token string) Option

WithAccessToken creates a client with an access token

func WithEventWebSocketURL

func WithEventWebSocketURL(url string) Option

WithEventWebSocketURL configures the event endpoint, including local test servers. The default vendor endpoint is experimental; callers must verify vendor support.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets a custom HTTP client for REST API calls.

func WithHardwareID

func WithHardwareID(hardwareID string) Option

WithHardwareID sets the hardware ID for authentication

func WithPassword

func WithPassword(password string) Option

WithPassword sets the password for authentication

func WithRTCWebSocketURL

func WithRTCWebSocketURL(url string) Option

WithRTCWebSocketURL sets a custom websocket URL for RTC streams (useful for testing)

func WithRefreshToken

func WithRefreshToken(refreshToken string) Option

WithRefreshToken creates a client with a refresh token

func WithTokenGetter

func WithTokenGetter(getter func(ctx context.Context) (string, error)) Option

WithTokenGetter sets a function to retrieve tokens dynamically

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent sets a custom user agent

func WithUsername

func WithUsername(username string) Option

WithUsername sets the username for authentication

type RTCStream

type RTCStream struct {
	// contains filtered or unexported fields
}

RTCStream represents an active RTC stream

func (*RTCStream) Close

func (rs *RTCStream) Close() error

Close closes the RTC stream

func (*RTCStream) GetDeviceID

func (rs *RTCStream) GetDeviceID() string

GetDeviceID returns the device ID

func (*RTCStream) GetSDPAnswer

func (rs *RTCStream) GetSDPAnswer() string

GetSDPAnswer returns the SDP answer

func (*RTCStream) GetStreamID

func (rs *RTCStream) GetStreamID() string

GetStreamID returns the stream ID (session ID)

func (*RTCStream) OnICECandidate

func (rs *RTCStream) OnICECandidate(candidate string, mlineIndex int) error

OnICECandidate can be called to send ICE candidates to the stream

type RefreshTokenRequest

type RefreshTokenRequest struct {
	RefreshToken string
}

RefreshTokenRequest contains parameters for RefreshToken

type Request2FACodeRequest

type Request2FACodeRequest struct {
	Username string
	Password string
}

Request2FACodeRequest contains parameters for Request2FACode

type SetInHomeChimeRequest

type SetInHomeChimeRequest struct {
	DeviceID string
	Settings map[string]interface{}
}

SetInHomeChimeRequest contains parameters for SetInHomeChime

type SetLightsRequest

type SetLightsRequest struct {
	DeviceID string
	State    string
	Duration *int
}

SetLightsRequest contains parameters for SetLights

type SetMotionDetectionRequest

type SetMotionDetectionRequest struct {
	DeviceID string
	Enabled  bool
}

SetMotionDetectionRequest contains parameters for SetMotionDetection

type SetVolumeRequest

type SetVolumeRequest struct {
	DeviceID string
	Volume   int
}

SetVolumeRequest contains parameters for SetVolume

type StartRTCStreamRequest

type StartRTCStreamRequest struct {
	DeviceID string
	SDPOffer string
}

StartRTCStreamRequest contains parameters for StartRTCStream

type StopRTCStreamRequest

type StopRTCStreamRequest struct {
	StreamID string
}

StopRTCStreamRequest contains parameters for StopRTCStream

type TestSoundRequest

type TestSoundRequest struct {
	DeviceID string
	Kind     string
}

TestSoundRequest contains parameters for TestSound

type UpdateDeviceHealthRequest

type UpdateDeviceHealthRequest struct {
	DeviceID string
}

UpdateDeviceHealthRequest contains parameters for UpdateDeviceHealth

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL