rest

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package rest provides a REST API client for interacting with Ring services. It supports authentication, device enumeration, control, and state management via HTTP/RESTful APIs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client is a REST API client for Ring services.

func NewClient 

func NewClient(opts ...ClientOption) *Client

NewClient creates a new REST API client.

func (*Client) Apply 

func (c *Client) Apply(opts ...ClientOption)

Apply applies the options to the client.

func (*Client) Authenticate 

func (c *Client) Authenticate(
	ctx context.Context,
	username, password, hardwareID, otpCode string,
) (*TokenResponse, error)

Authenticate performs Ring's OAuth 2.0 authorization-code flow with PKCE. The pending browser session is retained between the initial 2FA request and the subsequent call containing the verification code.

func (*Client) ConfigurationError added in v0.7.0 

func (c *Client) ConfigurationError() error

ConfigurationError returns an inspectable configuration error, if an option supplied an HTTP client that cannot be used safely.

func (*Client) DeleteRecording added in v0.3.0 

func (c *Client) DeleteRecording(ctx context.Context, id int64, confirmFavorite *bool) error

func (*Client) FavoriteRecording added in v0.3.0 

func (c *Client) FavoriteRecording(ctx context.Context, id int64) error

func (*Client) GetActiveDings 

func (c *Client) GetActiveDings(ctx context.Context) (generatedhttp.RecordingArray, error)

GetActiveDings retrieves currently active dings.

func (*Client) GetDeviceDetail added in v0.3.0 

func (c *Client) GetDeviceDetail(ctx context.Context, id int64) (*generatedhttp.DeviceDetail, error)

GetDeviceDetail returns the captured v3 detail envelope.

func (*Client) GetDeviceHealth 

func (c *Client) GetDeviceHealth(ctx context.Context, deviceID int64) (*generatedhttp.LegacyDeviceHealth, error)

GetDeviceHealth retrieves health data for a specific device.

func (*Client) GetDeviceHistory 

func (c *Client) GetDeviceHistory(
	ctx context.Context,
	deviceID int64,
	limit int,
	kind string,
	olderThan *int64,
) (generatedhttp.RecordingArray, error)

GetDeviceHistory retrieves the history of recordings for a device.

func (*Client) GetDeviceTimeline added in v0.3.0 

func (c *Client) GetDeviceTimeline(
	ctx context.Context,
	id int64,
	params generatedhttp.GetDeviceTimelineParams,
) (*generatedhttp.DeviceTimeline, error)

func (*Client) GetDevices 

func (c *Client) GetDevices(ctx context.Context) (*generatedhttp.DeviceList, error)

GetDevices retrieves all devices from the Ring API.

func (*Client) GetHistoryDevices added in v0.3.0 

func (c *Client) GetHistoryDevices(
	ctx context.Context,
	params generatedhttp.GetHistoryDevicesParams,
) (*generatedhttp.HistoryDevices, error)

func (*Client) GetLocation added in v0.3.0 

func (c *Client) GetLocation(
	ctx context.Context,
	id string,
	params generatedhttp.GetLocationParams,
) (*generatedhttp.LocationDetail, error)

func (*Client) GetMotionDetectionEnabled added in v0.3.0 

func (c *Client) GetMotionDetectionEnabled(ctx context.Context, deviceID int64) (*bool, error)

GetMotionDetectionEnabled reads the one settings field supported by the current typed public settings API. Other response fields are intentionally ignored.

func (*Client) GetRecording 

func (c *Client) GetRecording(ctx context.Context, recordingID int64) (*ringmedia.VideoStream, error)

GetRecording retrieves a video stream for a recording The endpoint returns video/mp4 directly in the response body.

func (*Client) GetRecordingShareURL added in v0.3.0 

func (c *Client) GetRecordingShareURL(ctx context.Context, recordingID int64) (string, error)

GetRecordingShareURL follows the pinned Python legacy share/play profile. The C1 recording does not establish this route's response.

func (*Client) GetSnapshotImage added in v0.3.0 

func (c *Client) GetSnapshotImage(ctx context.Context, deviceID int64) ([]byte, string, error)

GetSnapshotImage buffers one bounded JPEG response so the caller owns plain bytes rather than a live transport body.

func (*Client) HTTPClient 

func (c *Client) HTTPClient() *http.Client

HTTPClient returns a shallow copy of the configured HTTP client. Its Transport remains shared so connection pooling and custom transports work.

func (*Client) ListLocationDevices added in v0.3.0 

func (c *Client) ListLocationDevices(ctx context.Context, id string) (*generatedhttp.LocationGroupDevices, error)

func (*Client) ListLocationGroups added in v0.3.0 

func (c *Client) ListLocationGroups(ctx context.Context, id string) (*generatedhttp.LocationGroups, error)

func (*Client) ListLocations added in v0.3.0 

func (c *Client) ListLocations(ctx context.Context) (*generatedhttp.LocationList, error)

func (*Client) PatchMotionDetectionEnabled added in v0.3.0 

func (c *Client) PatchMotionDetectionEnabled(ctx context.Context, deviceID int64, enabled bool) error

PatchMotionDetectionEnabled changes only the captured motion detection field.

func (*Client) RebootDevice added in v0.3.0 

func (c *Client) RebootDevice(ctx context.Context, id int64) error

func (*Client) RefreshAccessToken 

func (c *Client) RefreshAccessToken(ctx context.Context, refreshToken string) (*TokenResponse, error)

RefreshAccessToken refreshes an access token using a refresh token.

func (*Client) RefreshAccessTokenFor added in v0.3.0 

func (c *Client) RefreshAccessTokenFor(ctx context.Context, refreshToken, hardwareID string) (*TokenResponse, error)

RefreshAccessTokenFor uses a caller-supplied device identity without changing authorization state on a shared REST client.

func (*Client) RefreshSnapshotTimestamp added in v0.3.0 

func (c *Client) RefreshSnapshotTimestamp(ctx context.Context, deviceID int64) (int64, error)

RefreshSnapshotTimestamp uses the pinned Python legacy profile. The first response may have no timestamp; callers trigger once, then poll for freshness.

func (*Client) RegisterPushDevice added in v0.4.0 

func (c *Client) RegisterPushDevice(ctx context.Context, token string) error

RegisterPushDevice binds an FCM token to the authenticated Ring account.

func (*Client) RegisterSession added in v0.2.0 

func (c *Client) RegisterSession(ctx context.Context) error

RegisterSession registers the client hardware ID with Ring before API use.

func (*Client) Request2FACode 

func (c *Client) Request2FACode(ctx context.Context, username, password, hardwareID string) error

Request2FACode starts the PKCE login flow and causes Ring to deliver a code.

func (*Client) SetChimeVolume added in v0.3.0 

func (c *Client) SetChimeVolume(ctx context.Context, deviceID int64, description string, volume int) error

SetChimeVolume uses the Python legacy chime update profile.

func (*Client) SetDoorbellVolume added in v0.3.0 

func (c *Client) SetDoorbellVolume(ctx context.Context, deviceID int64, description string, volume int) error

SetDoorbellVolume uses the Python legacy doorbot update profile.

func (*Client) SetInHomeChimeDuration added in v0.3.0 

func (c *Client) SetInHomeChimeDuration(ctx context.Context, deviceID int64, description string, value int) error

SetInHomeChimeDuration changes the legacy duration field.

func (*Client) SetInHomeChimeEnabled added in v0.3.0 

func (c *Client) SetInHomeChimeEnabled(ctx context.Context, deviceID int64, description string, enabled bool) error

SetInHomeChimeEnabled changes the legacy enable field.

func (*Client) SetInHomeChimeType added in v0.3.0 

func (c *Client) SetInHomeChimeType(ctx context.Context, deviceID int64, description string, value int) error

SetInHomeChimeType changes the legacy type field.

func (*Client) SetLights 

func (c *Client) SetLights(ctx context.Context, deviceID int64, enabled bool) error

SetLights uses the captured on route and the corresponding legacy off route.

func (*Client) SetMotionDetection 

func (c *Client) SetMotionDetection(ctx context.Context, deviceID int64, enabled bool) error

SetMotionDetection shares the recorded typed settings PATCH route.

func (*Client) SetPersistentLiveViewEnabled added in v0.3.0 

func (c *Client) SetPersistentLiveViewEnabled(ctx context.Context, id int64, enabled bool) error

func (*Client) SetSiren added in v0.3.0 

func (c *Client) SetSiren(ctx context.Context, deviceID int64, enabled bool) error

SetSiren toggles the captured legacy doorbot siren route. Duration is not configurable: the capture establishes the server's response duration only.

func (*Client) SubscribeDeviceDing added in v0.4.0 

func (c *Client) SubscribeDeviceDing(ctx context.Context, id int64) error

func (*Client) SubscribeDeviceMotion added in v0.4.0 

func (c *Client) SubscribeDeviceMotion(ctx context.Context, id int64) error

func (*Client) TestSound 

func (c *Client) TestSound(ctx context.Context, deviceID int64, kind generatedhttp.TestChimeSoundParamsKind) error

TestSound uses the Python legacy chime route and query parameter.

func (*Client) UnlockIntercom added in v0.4.0 

func (c *Client) UnlockIntercom(ctx context.Context, id int64) error

UnlockIntercom sends the documented device RPC to an intercom.

type ClientOption 

type ClientOption func(*Client)

ClientOption is a function that configures a Client.

func WithBaseURI 

func WithBaseURI(baseURL string) ClientOption

WithBaseURI sets the base URL for the Ring API.

func WithEndpointBases added in v0.3.0 

func WithEndpointBases(apiBase, oauthBase string) ClientOption

WithEndpointBases configures per-client Ring service origins.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client snapshot. A configured cookie jar is reported by Client.ConfigurationError and blocks requests.

func WithHardwareID 

func WithHardwareID(hardwareID string) ClientOption

WithHardwareID sets the hardware ID for authentication.

func WithUserAgent 

func WithUserAgent(userAgent string) ClientOption

WithUserAgent sets a custom user agent.

type HTTPClientConfigurationError added in v0.7.0 

type HTTPClientConfigurationError struct {
	Reason string
}

HTTPClientConfigurationError reports an unsafe or unusable HTTP client supplied to a reusable REST client.

func (*HTTPClientConfigurationError) Error added in v0.7.0 

func (e *HTTPClientConfigurationError) Error() string

type TokenResponse 

type TokenResponse = generatedhttp.OAuthToken

TokenResponse is generated from the OAuthToken schema in api/openapi.yaml.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.