api

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Feb 4, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	BaseURL     = "https://api.raindrop.io/rest/v1"
	UserAgent   = "raindrop-cli/0.1.0"
	ContentType = "application/json"
)
View Source 
const (
	ExitSuccess   = 0
	ExitError     = 1
	ExitUsage     = 2
	ExitAuth      = 3
	ExitNotFound  = 4
	ExitRateLimit = 5
)
View Source 
const (
	MaxRateLimitRetries   = 3
	Max5xxRetries         = 1
	RateLimitBaseDelay    = 1 * time.Second
	ServerErrorRetryDelay = 2 * time.Second
)
View Source 
const SystemCollectionAll = 0

SystemCollectionAll represents all raindrops.

View Source 
const SystemCollectionTrash = -99

SystemCollectionTrash represents trashed raindrops.

View Source 
const SystemCollectionUnsorted = -1

SystemCollectionUnsorted represents unsorted raindrops.

Variables

View Source 
var (
	ErrNotAuthenticated = errors.New("not authenticated")
	ErrRateLimited      = errors.New("rate limit exceeded")
	ErrNotFound         = errors.New("not found")
)

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
	Details    string
}

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) ExitCode 

func (e *APIError) ExitCode() int

type AuthError 

type AuthError struct {
	Err error
}

func (*AuthError) Error 

func (e *AuthError) Error() string

func (*AuthError) Unwrap 

func (e *AuthError) Unwrap() error

type BulkCreateRequest 

type BulkCreateRequest struct {
	Items []CreateRaindropRequest `json:"items"`
}

BulkCreateRequest wraps bulk create payload.

type BulkCreateResponse 

type BulkCreateResponse struct {
	Items  []Raindrop `json:"items"`
	Result bool       `json:"result"`
}

BulkCreateResponse wraps bulk create response.

type Client 

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

Client is the Raindrop.io API client.

func NewClient 

func NewClient(ts oauth2.TokenSource) *Client

NewClient creates a new API client with the given token source.

func NewClientFromAuth 

func NewClientFromAuth() (*Client, error)

NewClientFromAuth creates a client using stored auth credentials.

func NewClientWithBaseURL 

func NewClientWithBaseURL(ts oauth2.TokenSource, baseURL string) *Client

NewClientWithBaseURL creates a new API client with a custom base URL.

func (*Client) CreateCollection 

func (c *Client) CreateCollection(ctx context.Context, req *CreateCollectionRequest) (*Collection, error)

CreateCollection creates a new collection.

func (*Client) CreateRaindrop 

func (c *Client) CreateRaindrop(ctx context.Context, req *CreateRaindropRequest) (*Raindrop, error)

CreateRaindrop creates a new raindrop.

func (*Client) CreateRaindropsBulk 

func (c *Client) CreateRaindropsBulk(ctx context.Context, items []CreateRaindropRequest) ([]Raindrop, error)

CreateRaindropsBulk creates multiple raindrops (max 100 per call).

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, path string) error

Delete performs a DELETE request.

func (*Client) DeleteCollection 

func (c *Client) DeleteCollection(ctx context.Context, id int) error

DeleteCollection deletes a collection.

func (*Client) DeleteRaindrop 

func (c *Client) DeleteRaindrop(ctx context.Context, id int, permanent bool) error

DeleteRaindrop moves a raindrop to trash, or permanently deletes if permanent=true.

func (*Client) DeleteTags 

func (c *Client) DeleteTags(ctx context.Context, collectionID int, tags []string) error

DeleteTags removes tags from a collection.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, out interface{}) error

Get performs a GET request.

func (*Client) GetCollection 

func (c *Client) GetCollection(ctx context.Context, id int) (*Collection, error)

GetCollection fetches a single collection by ID.

func (*Client) GetRaindrop 

func (c *Client) GetRaindrop(ctx context.Context, id int) (*Raindrop, error)

GetRaindrop fetches a single raindrop by ID.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context) (*User, error)

GetUser returns the authenticated user's info.

func (*Client) ListAllCollections 

func (c *Client) ListAllCollections(ctx context.Context) ([]Collection, error)

ListAllCollections fetches both root and child collections.

func (*Client) ListChildCollections 

func (c *Client) ListChildCollections(ctx context.Context) ([]Collection, error)

ListChildCollections fetches all child collections.

func (*Client) ListRaindrops 

func (c *Client) ListRaindrops(ctx context.Context, collectionID int, opts ListOptions) (*RaindropsResponse, error)

ListRaindrops fetches raindrops from a collection. collectionID: 0 = all, -1 = unsorted, -99 = trash

func (*Client) ListRootCollections 

func (c *Client) ListRootCollections(ctx context.Context) ([]Collection, error)

ListRootCollections fetches all root-level collections.

func (*Client) ListTags 

func (c *Client) ListTags(ctx context.Context, collectionID int) ([]Tag, error)

ListTags fetches all tags for a collection. collectionID: 0 = all collections

func (*Client) ParseURL 

func (c *Client) ParseURL(ctx context.Context, rawURL string) (*ParsedURL, error)

ParseURL fetches metadata for a URL (title, excerpt, type, cover).

func (*Client) Post 

func (c *Client) Post(ctx context.Context, path string, body interface{}, out interface{}) error

Post performs a POST request.

func (*Client) Put 

func (c *Client) Put(ctx context.Context, path string, body interface{}, out interface{}) error

Put performs a PUT request.

func (*Client) RenameTags 

func (c *Client) RenameTags(ctx context.Context, collectionID int, oldTags []string, newName string) error

RenameTags renames tags in a collection.

func (*Client) ResolveCollection 

func (c *Client) ResolveCollection(ctx context.Context, nameOrID string) (int, error)

ResolveCollection converts a name or ID string to a collection ID. Supports: numeric ID, "all" (0), "unsorted" (-1), "trash" (-99), or name lookup.

func (*Client) Token 

func (c *Client) Token(ctx context.Context) (*oauth2.Token, error)

Token returns the current OAuth token.

func (*Client) UpdateCollection 

func (c *Client) UpdateCollection(ctx context.Context, id int, req *UpdateCollectionRequest) (*Collection, error)

UpdateCollection updates an existing collection.

func (*Client) UpdateRaindrop 

func (c *Client) UpdateRaindrop(ctx context.Context, id int, req *UpdateRaindropRequest) (*Raindrop, error)

UpdateRaindrop updates an existing raindrop.

type Collection 

type Collection struct {
	ID       int            `json:"_id"`
	Title    string         `json:"title"`
	Count    int            `json:"count"`
	Color    string         `json:"color,omitempty"`
	Parent   *CollectionRef `json:"parent,omitempty"`
	Expanded bool           `json:"expanded"`
	Created  time.Time      `json:"created"`
	Updated  time.Time      `json:"lastUpdate"`
}

Collection represents a Raindrop.io collection.

func (*Collection) ParentID 

func (c *Collection) ParentID() int

ParentID returns the parent collection ID, or 0 if no parent.

type CollectionRef 

type CollectionRef struct {
	ID int `json:"$id"`
}

CollectionRef is a reference to a collection (used in API responses).

type CollectionResponse 

type CollectionResponse struct {
	Item   Collection `json:"item"`
	Result bool       `json:"result"`
}

CollectionResponse wraps a single collection.

type CollectionsResponse 

type CollectionsResponse struct {
	Items  []Collection `json:"items"`
	Result bool         `json:"result"`
}

CollectionsResponse wraps a list of collections.

type CreateCollectionRequest 

type CreateCollectionRequest struct {
	Title  string `json:"title"`
	Parent *struct {
		ID int `json:"$id"`
	} `json:"parent,omitempty"`
	Color string `json:"color,omitempty"`
}

CreateCollectionRequest is the payload for creating a collection.

type CreateRaindropRequest 

type CreateRaindropRequest struct {
	Link       string   `json:"link,omitempty"`
	Title      string   `json:"title,omitempty"`
	Excerpt    string   `json:"excerpt,omitempty"`
	Note       string   `json:"note,omitempty"`
	Tags       []string `json:"tags,omitempty"`
	Important  bool     `json:"important,omitempty"`
	Collection struct {
		ID int `json:"$id"`
	} `json:"collection,omitempty"`
	PleaseParse bool `json:"pleaseParse,omitempty"` //nolint:tagliatelle // API uses camelCase
}

CreateRaindropRequest is the payload for creating a raindrop.

type DeleteTagsRequest 

type DeleteTagsRequest struct {
	Tags []string `json:"tags"`
}

DeleteTagsRequest is the payload for deleting tags.

type Highlight 

type Highlight struct {
	ID      string    `json:"_id"`
	Text    string    `json:"text"`
	Note    string    `json:"note,omitempty"`
	Color   string    `json:"color,omitempty"`
	Created time.Time `json:"created"`
}

Highlight represents a text highlight in a raindrop.

type ListOptions 

type ListOptions struct {
	Search  string
	Sort    string
	Page    int
	PerPage int
}

ListOptions configures list/search requests.

type NotFoundError 

type NotFoundError struct {
	Resource string
	ID       string
}

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type ParsedURL 

type ParsedURL struct {
	Result bool `json:"result"`
	Item   struct {
		Title   string `json:"title"`
		Excerpt string `json:"excerpt"`
		Type    string `json:"type"`
		Cover   string `json:"cover"`
	} `json:"item"`
}

ParsedURL represents the response from /import/url/parse.

type Raindrop 

type Raindrop struct {
	ID         int            `json:"_id"`
	Link       string         `json:"link"`
	Title      string         `json:"title"`
	Excerpt    string         `json:"excerpt"`
	Note       string         `json:"note"`
	Type       string         `json:"type"`
	Tags       []string       `json:"tags"`
	Important  bool           `json:"important"`
	Collection *CollectionRef `json:"collection,omitempty"`
	Cover      string         `json:"cover"`
	Domain     string         `json:"domain"`
	Created    time.Time      `json:"created"`
	Updated    time.Time      `json:"lastUpdate"`
	Highlights []Highlight    `json:"highlights,omitempty"`
}

Raindrop represents a bookmark in Raindrop.io.

func (*Raindrop) CollectionID 

func (r *Raindrop) CollectionID() int

CollectionID returns the collection ID, or 0 if none.

type RaindropResponse 

type RaindropResponse struct {
	Item   Raindrop `json:"item"`
	Result bool     `json:"result"`
}

RaindropResponse wraps a single raindrop response.

type RaindropsResponse 

type RaindropsResponse struct {
	Items []Raindrop `json:"items"`
	Count int        `json:"count"`
}

RaindropsResponse wraps a list of raindrops.

type RateLimitError 

type RateLimitError struct {
	RetryAfter int // seconds
}

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

type RenameTagRequest 

type RenameTagRequest struct {
	Tags    []string `json:"tags"`
	Replace string   `json:"replace"`
}

RenameTagRequest is the payload for renaming a tag.

type RetryTransport 

type RetryTransport struct {
	Base          http.RoundTripper
	MaxRetries429 int
	MaxRetries5xx int
	BaseDelay     time.Duration
}

RetryTransport wraps an http.RoundTripper with retry logic for rate limits (429) and server errors (5xx).

func NewRetryTransport 

func NewRetryTransport(base http.RoundTripper) *RetryTransport

func (*RetryTransport) RoundTrip 

func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error)

type Tag 

type Tag struct {
	Tag   string `json:"_id"`
	Count int    `json:"count"`
}

Tag represents a tag with usage count.

type TagsResponse 

type TagsResponse struct {
	Items []Tag `json:"items"`
}

TagsResponse wraps a list of tags.

type UpdateCollectionRequest 

type UpdateCollectionRequest struct {
	Title  string `json:"title,omitempty"`
	Parent *struct {
		ID int `json:"$id"`
	} `json:"parent,omitempty"`
	Color string `json:"color,omitempty"`
}

UpdateCollectionRequest is the payload for updating a collection.

type UpdateRaindropRequest 

type UpdateRaindropRequest struct {
	Link       string   `json:"link,omitempty"`
	Title      string   `json:"title,omitempty"`
	Excerpt    string   `json:"excerpt,omitempty"`
	Note       string   `json:"note,omitempty"`
	Tags       []string `json:"tags,omitempty"`
	Important  *bool    `json:"important,omitempty"`
	Collection *struct {
		ID int `json:"$id"`
	} `json:"collection,omitempty"`
}

UpdateRaindropRequest is the payload for updating a raindrop.

type User 

type User struct {
	ID       int    `json:"_id"`
	FullName string `json:"fullName"`
	Email    string `json:"email"`
	Pro      bool   `json:"pro"`
}

User represents a Raindrop.io user.

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.