From: Florian Forster Date: Wed, 31 Jan 2018 15:33:09 +0000 (+0100) Subject: Package fitbit: Add documentation. X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=0b5456de50f3e76354cb3222fa16a7dfd5b066bf;p=kraftakt.git Package fitbit: Add documentation. --- diff --git a/fitbit/fitbit.go b/fitbit/fitbit.go index 7e38bf1..33f2ccd 100644 --- a/fitbit/fitbit.go +++ b/fitbit/fitbit.go @@ -1,3 +1,4 @@ +// Package fitbit implements functions to interact with the Fitbit API. package fitbit import ( @@ -34,10 +35,14 @@ func oauthConfig() *oauth2.Config { } } +// AuthURL returns the URL of the Fitbit consent screen. Users are redirected +// there to approve Fitbit minting an OAuth2 token for us. func AuthURL(ctx context.Context, u *app.User) string { return oauthConfig().AuthCodeURL(u.Sign("Fitbit"), oauth2.AccessTypeOffline) } +// ParseToken parses the request of the user being redirected back from the +// consent screen. The parsed token is stored in u using SetToken(). func ParseToken(ctx context.Context, r *http.Request, u *app.User) error { if state := r.FormValue("state"); state != u.Sign("Fitbit") { return fmt.Errorf("invalid state parameter: %q", state) @@ -51,6 +56,9 @@ func ParseToken(ctx context.Context, r *http.Request, u *app.User) error { return u.SetToken(ctx, "Fitbit", tok) } +// CheckSignature validates that rawSig is a valid signature of payload. This +// is used by the Fitbit API to ansure that the receiver can verify that the +// sender has access to the OAuth2 client secret. func CheckSignature(ctx context.Context, payload []byte, rawSig string) bool { signatureGot, err := base64.StdEncoding.DecodeString(rawSig) if err != nil { @@ -160,6 +168,9 @@ func NewClient(ctx context.Context, fitbitUserID string, u *app.User) (*Client, }, nil } +// ActivitySummary returns the daily activity summary. +// +// See https://dev.fitbit.com/build/reference/web-api/activity/#get-daily-activity-summary for details. func (c *Client) ActivitySummary(ctx context.Context, date string) (*ActivitySummary, error) { url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/activities/date/%s.json", c.fitbitUserID, date) @@ -188,11 +199,17 @@ func (c *Client) subscriberID(collection string) string { return fmt.Sprintf("%s:%s", c.appUser.ID, collection) } +// UserFromSubscriberID parses the user ID from the subscriber ID and calls +// app.UserByID() with the user ID. func UserFromSubscriberID(ctx context.Context, subscriberID string) (*app.User, error) { uid := strings.Split(subscriberID, ":")[0] return app.UserByID(ctx, uid) } +// Subscribe subscribes to one collection of the user. It uses a per-collection +// subscription ID so that we can subscribe to more than one collection. +// +// See https://dev.fitbit.com/build/reference/web-api/subscriptions/#adding-a-subscription for details. func (c *Client) Subscribe(ctx context.Context, collection string) error { url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/%s/apiSubscriptions/%s.json", c.fitbitUserID, collection, c.subscriberID(collection)) @@ -244,6 +261,10 @@ func (c *Client) unsubscribe(ctx context.Context, userID, collection, subscripti return nil } +// UnsubscribeAll gets a list of all subscriptions we have with the user's +// account and deletes all found subscriptions. +// +// See https://dev.fitbit.com/build/reference/web-api/subscriptions/#deleting-a-subscription for details. func (c *Client) UnsubscribeAll(ctx context.Context) error { var errs appengine.MultiError @@ -267,6 +288,8 @@ func (c *Client) UnsubscribeAll(ctx context.Context) error { return nil } +// ListSubscriptions returns a list of all subscriptions for a given collection +// the OAuth2 client has to a user's account. func (c *Client) ListSubscriptions(ctx context.Context, collection string) ([]Subscription, error) { url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/%s/apiSubscriptions.json", c.fitbitUserID, collection) res, err := c.client.Get(url) @@ -325,15 +348,19 @@ func (c *Client) ListSubscriptions(ctx context.Context, collection string) ([]Su return ret, nil } +// DeleteToken deletes the Fitbit OAuth2 token. func (c *Client) DeleteToken(ctx context.Context) error { return c.appUser.DeleteToken(ctx, "Fitbit") } +// Provile contains data about the user. +// It only contains the subset of fields required by Kraftakt. type Profile struct { Name string Timezone *time.Location } +// Profile returns the profile information of the user. func (c *Client) Profile(ctx context.Context) (*Profile, error) { res, err := c.client.Get("https://api.fitbit.com/1/user/-/profile.json") if err != nil {