rest

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 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) 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 the underlying HTTP client.

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.

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