goflume

package module
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Jun 9, 2025 License: Apache-2.0 Imports: 11 Imported by: 0

README ΒΆ

Go Flume API Client

Go Flume API Client

A Go client for the Flume Personal API.

Version Documentation Maintenance Coverage PayPal


πŸ“‹ Table of Contents


πŸ‘€ Overview

go-flume is an idiomatic Go client designed to interact with the Flume Personal API.

The Flume Personal API enables developers to create custom tools and integrations for managing their Flume devices. It is intended solely for personal use.

The API is still being actively developed and is subject to change at any time.

For official API documentation, see:
https://flumetech.readme.io/reference/introduction


πŸŽ› Features

  • OAuth2 authentication
  • Comprehensive API coverage: Query user, device, usage, flow, location, budget, subscription, notification, alert, contact, and rule data
  • Flexible query parameters: Some methods accept optional parameter structs for filtering, sorting, and pagination
  • Idiomatic Go types: Strongly typed models for all API resources
  • Robust error handling: All methods return error values
  • Easy integration: Simple client setup and usage with context support
  • Actively maintained and well-documented

πŸ’Ύ Installation

Install the package using go get:

go get github.com/401unauthorized/go-flume

πŸš€ Usage

1. Create the Client

import (
    "context"
    "log"
    goflume "github.com/401unauthorized/go-flume"
)

func main() {
    client := goflume.NewClient(
        "your-client-id",
        "your-client-secret",
        nil, // Use default HTTP client
    )

    // Authenticate
    err := client.Authenticate(context.Background(), "your-username", "your-password")
    if err != nil {
        log.Fatal("Authentication failed:", err)
    }

    // Example: Get user info
    user, err := client.GetUser(context.Background())
    if err != nil {
        log.Fatal("GetUser failed:", err)
    }
}

πŸ” Authentication

  • Authenticate(ctx, username, password) error Authenticate with Flume username and password.

  • RefreshAccessToken(ctx) error Refresh the access token using the refresh token.

    The client does not handle token refreshes when making API calls, so you need to call this manually.


πŸ›  API Methods

All methods accept a context and return a structured result and an error.

User

  • GetUser(ctx) (*UserResponse, error)

Devices

  • GetDevices(ctx, params *DevicesParams) (*DevicesResponse, error)
  • GetDevice(ctx, deviceID string, params *DeviceParams) (*DeviceResponse, error)

Usage & Flow

  • QueryUsage(ctx, deviceID string, req QueryUsageRequestBody) (*QueryUsageResponse, error)
  • GetCurrentFlow(ctx, deviceID string) (*FlowResponse, error)

Locations

  • GetLocations(ctx, params *GetLocationsParams) (*LocationsResponse, error)
  • GetLocation(ctx, locationID string) (*LocationResponse, error)
  • UpdateLocation(ctx, locationID string, patch LocationPatch) (*APIResponseEnvelope, error)

Budgets

  • GetBudgets(ctx, deviceID string, params *GetBudgetsParams) (*BudgetsResponse, error)

Subscriptions

  • GetSubscriptions(ctx, params *GetSubscriptionsParams) (*SubscriptionsResponse, error)
  • GetSubscription(ctx, subscriptionID string) (*SubscriptionResponse, error)

Notifications

  • GetNotifications(ctx, params *GetNotificationsParams) (*NotificationsResponse, error)

Alerts

  • GetUsageAlerts(ctx, params *GetUsageAlertsParams) (*UsageAlertsResponse, error)

Event Rules & Usage Alert Rules

  • GetEventRules(ctx, deviceID string, params *GetEventRulesParams) (*EventRulesResponse, error)
  • GetUsageAlertRules(ctx, deviceID string, params *GetUsageAlertRulesParams) (*UsageAlertRulesResponse, error)
  • GetUsageAlertRule(ctx, deviceID, ruleID string) (*UsageAlertRuleResponse, error)

Contacts

  • GetContacts(ctx, params *GetContactsParams) (*ContactsResponse, error)

πŸ“ License

Copyright Β© 2025 Stephen Mendez

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


⚠️ Disclaimer

This client is not affiliated with Flume, Inc. Use at your own risk.

Trademark Notices

Flume, the Flume logo, FlumeTech, HomeHealth, FlumePro, and Get to Know Your H2O are registered trademarks of Flume, Inc. in the United States and FlumeWater is a trademark of Flume, Inc.

All other trademarks referenced herein are the property of their respective owners.

Documentation ΒΆ

Index ΒΆ

Constants ΒΆ

View Source
const BaseApiUrl = "https://api.flumewater.com"

Variables ΒΆ

This section is empty.

Functions ΒΆ

This section is empty.

Types ΒΆ

type APIResponseEnvelope ΒΆ

type APIResponseEnvelope struct {
	Success     bool   `json:"success"`
	Code        int    `json:"code"`
	Message     string `json:"message"`
	HTTPCode    int    `json:"http_code"`
	HTTPMessage string `json:"http_message"`
	Detailed    string `json:"detailed"`
	Count       int    `json:"count"`
	Pagination  string `json:"pagination"`
}

type APIResponseEnvelopePagination ΒΆ

type APIResponseEnvelopePagination struct {
	Success     bool       `json:"success"`
	Code        int        `json:"code"`
	Message     string     `json:"message"`
	HTTPCode    int        `json:"http_code"`
	HTTPMessage string     `json:"http_message"`
	Detailed    string     `json:"detailed"`
	Count       int        `json:"count"`
	Pagination  Pagination `json:"pagination"`
}

type Budget ΒΆ

type Budget struct {
	ID         int    `json:"id"`
	Name       string `json:"name"`
	Type       string `json:"type"`
	Value      int    `json:"value"`
	Thresholds []int  `json:"thresholds"`
	Actual     int    `json:"actual"`
}

type BudgetsResponse ΒΆ

type BudgetsResponse struct {
	APIResponseEnvelope
	Data []Budget `json:"data"`
}

type Client ΒΆ

type Client struct {
	BaseURL      string
	ClientID     string
	ClientSecret string
	HTTPClient   *http.Client
	Token        Token
	JWT          JWTPayload
}

func NewClient ΒΆ

func NewClient(clientID, clientSecret string, httpClient *http.Client) *Client

func (*Client) Authenticate ΒΆ

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

func (*Client) GetBudgets ΒΆ

func (c *Client) GetBudgets(ctx context.Context, deviceID string, params *GetBudgetsParams) (*BudgetsResponse, error)

func (*Client) GetContacts ΒΆ

func (c *Client) GetContacts(ctx context.Context, params *GetContactsParams) (*ContactsResponse, error)

func (*Client) GetCurrentFlow ΒΆ

func (c *Client) GetCurrentFlow(ctx context.Context, deviceID string) (*FlowResponse, error)

func (*Client) GetDevice ΒΆ

func (c *Client) GetDevice(ctx context.Context, deviceID string, params *DeviceParams) (*DeviceResponse, error)

func (*Client) GetDevices ΒΆ

func (c *Client) GetDevices(ctx context.Context, params *DevicesParams) (*DevicesResponse, error)

func (*Client) GetEventRules ΒΆ

func (c *Client) GetEventRules(ctx context.Context, deviceID string, params *GetEventRulesParams) (*EventRulesResponse, error)

func (*Client) GetLocation ΒΆ

func (c *Client) GetLocation(ctx context.Context, locationID string) (*LocationResponse, error)

func (*Client) GetLocations ΒΆ

func (c *Client) GetLocations(ctx context.Context, params *GetLocationsParams) (*LocationsResponse, error)

func (*Client) GetNotifications ΒΆ

func (c *Client) GetNotifications(ctx context.Context, params *GetNotificationsParams) (*NotificationsResponse, error)

func (*Client) GetSubscription ΒΆ

func (c *Client) GetSubscription(ctx context.Context, subscriptionID string) (*SubscriptionResponse, error)

func (*Client) GetSubscriptions ΒΆ

func (c *Client) GetSubscriptions(ctx context.Context, params *GetSubscriptionsParams) (*SubscriptionsResponse, error)

func (*Client) GetUsageAlertRule ΒΆ

func (c *Client) GetUsageAlertRule(ctx context.Context, deviceID, ruleID string) (*UsageAlertRuleResponse, error)

func (*Client) GetUsageAlertRules ΒΆ

func (c *Client) GetUsageAlertRules(ctx context.Context, deviceID string, params *GetUsageAlertRulesParams) (*UsageAlertRulesResponse, error)

func (*Client) GetUsageAlerts ΒΆ

func (c *Client) GetUsageAlerts(ctx context.Context, params *GetUsageAlertsParams) (*UsageAlertsResponse, error)

func (*Client) GetUser ΒΆ

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

func (*Client) QueryUsage ΒΆ

func (c *Client) QueryUsage(ctx context.Context, deviceID string, data QueryUsageRequestBody) (*QueryUsageResponse, error)

func (*Client) RefreshAccessToken ΒΆ

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

func (*Client) UpdateLocation ΒΆ

func (c *Client) UpdateLocation(ctx context.Context, locationID string, patch LocationPatch) (*APIResponseEnvelope, error)

type Contact ΒΆ

type Contact struct {
	ID       int    `json:"id"`
	Category string `json:"category"`
	Type     string `json:"type"`
	Detail   string `json:"detail"`
}

type ContactsResponse ΒΆ

type ContactsResponse struct {
	APIResponseEnvelope
	Data []Contact `json:"data"`
}

type Device ΒΆ

type Device struct {
	ID           string `json:"id"`
	Type         int    `json:"type"`
	LocationID   int    `json:"location_id"`
	UserID       int    `json:"user_id"`
	BridgeID     string `json:"bridge_id"`
	Oriented     bool   `json:"oriented"`
	LastSeen     string `json:"last_seen"`
	Connected    bool   `json:"connected"`
	BatteryLevel string `json:"battery_level"`
	Product      string `json:"product"`
}

type DeviceParams ΒΆ

type DeviceParams struct {
	User     *bool // Include user data in response (Defaults to false)
	Location *bool // Include location data in response (Defaults to false)
}

type DeviceResponse ΒΆ

type DeviceResponse struct {
	APIResponseEnvelope
	Data []Device `json:"data"`
}

type DevicesParams ΒΆ

type DevicesParams struct {
	Limit           *int32  // How many devices to return (Defaults to 50)
	Offset          *int32  // Offset of devices to return (Defaults to 0)
	SortField       *string // Which field to sort devices on (Defaults to id)
	SortDirection   *string // Which direction to sort devices on (Defaults to ASC)
	User            *bool   // Include user data in response (Defaults to false)
	Location        *bool   // Include location data in response (Defaults to false)
	ListShared      *bool   // Include devices with shared access (Defaults to false)
	PrimaryLocation *bool   // Only include devices associated with a primary location if true
	LocationID      *int32  // Find devices associated with a specified location ID
	Type            *int32  // Filter devices by their type
}

type DevicesResponse ΒΆ

type DevicesResponse struct {
	APIResponseEnvelope
	Data []Device `json:"data"`
}

type EventRule ΒΆ

type EventRule struct {
	ID               string  `json:"id"`
	Name             string  `json:"name"`
	Active           bool    `json:"active"`
	FlowRate         float64 `json:"flow_rate"`
	Duration         int     `json:"duration"`
	NotifyEvery      int     `json:"notify_every"`
	NotificationType string  `json:"notification_type"`
}

type EventRulesResponse ΒΆ

type EventRulesResponse struct {
	APIResponseEnvelope
	Data []EventRule `json:"data"`
}

type Flow ΒΆ

type Flow struct {
	Active   bool    `json:"active"`
	GPM      float64 `json:"gpm"`
	Datetime string  `json:"datetime"`
}

type FlowResponse ΒΆ

type FlowResponse struct {
	APIResponseEnvelope
	Data []Flow `json:"data"`
}

type GetBudgetsParams ΒΆ

type GetBudgetsParams struct {
	Limit         *int32  // Max number of budgets to return (Defaults to 50)
	Offset        *int32  // Offset of budgets to return (Defaults to 0)
	SortField     *string // Field to sort budgets on (Defaults to id)
	SortDirection *string // Which direction to sort budgets on (Defaults to ASC)
}

type GetContactsParams ΒΆ

type GetContactsParams struct {
	Limit         *int32  // Max number of contacts to return (Defaults to 50)
	Offset        *int32  // Offset of contacts to return (Defaults to 0)
	SortField     *string // Field to sort contacts on (Defaults to id)
	SortDirection *string // Sort direction (Defaults to ASC)
	Type          *string // Filter by this type of contact information
	Category      *string // Filter by this category of contact information
}

type GetEventRulesParams ΒΆ

type GetEventRulesParams struct {
	Limit         *int32  // Max number of event rules to return (Defaults to 50)
	Offset        *int32  // Offset of event rules to return (Defaults to 0)
	SortField     *string // Field to sort event rules on (Defaults to id)
	SortDirection *string // Sort direction (Defaults to ASC)
}

type GetLocationsParams ΒΆ

type GetLocationsParams struct {
	Limit         *int32  // Max number of locations to return (Defaults to 50)
	Offset        *int32  // Offset of locations to return (Defaults to 0)
	SortField     *string // Field to sort locations on (Defaults to id)
	SortDirection *string // Which direction to sort locations on (Defaults to ASC)
	ListShared    *bool   // Include locations with shared access (Defaults to false)
}

type GetNotificationsParams ΒΆ

type GetNotificationsParams struct {
	Limit         *int32  // How many notifications to return (Defaults to 50)
	Offset        *int32  // Offset of notifications to return (Defaults to 0)
	SortField     *string // Which field to sort notifications on (Defaults to created_datetime)
	SortDirection *string // Which direction to sort notifications on (Defaults to ASC)
	DeviceID      *string // Return notifications sent from a device with this device_id
	LocationID    *int32  // Returns notifications for this location
	Type          *int32  // Filter notifications by this type
	Types         *int32  // Return notifications of the bitmask of notification types
	Read          *bool   // Filter by notifications that are read or not
}

type GetSubscriptionsParams ΒΆ

type GetSubscriptionsParams struct {
	Limit             *int32  // How many subscriptions to return (Defaults to 50)
	Offset            *int32  // Offset of subscriptions to return (Defaults to 0)
	SortField         *string // Which field to sort the subscriptions on (Defaults to id)
	SortDirection     *string // The direction to sort the subscriptions on (Defaults to ASC)
	AlertType         *string // Only return subscriptions with this alert type
	NotificationTypes *int32  // Only return subscriptions that subscribe to the exact bitmask of notification types
	NotificationType  *int32  // Return all subscriptions that contain the bit
	DeviceID          *string // Only return subscriptions that are for this device
	DeviceType        *int32  // Only return subscriptions for devices of this type
	LocationID        *int32  // Only return subscriptions that are associated with a device at this location
}

type GetUsageAlertRulesParams ΒΆ

type GetUsageAlertRulesParams struct {
	Limit         *int32  // Max number of event rules to return (Defaults to 50)
	Offset        *int32  // Offset of event rules to return (Defaults to 0)
	SortField     *string // Field to sort event rules on (Defaults to id)
	SortDirection *string // Sort direction (Defaults to ASC)
}

type GetUsageAlertsParams ΒΆ

type GetUsageAlertsParams struct {
	Limit         *int32  // How many usage alerts to return (Defaults to 50)
	Offset        *int32  // Offset of usage alerts to return (Defaults to 0)
	SortField     *string // Which field to sort usage alerts on (Defaults to id)
	SortDirection *string // Which direction to sort usage alerts on (Defaults to ASC)
	DeviceID      *string // Return usage alerts for this device_id
	FlumeLeak     *bool   // Returns usage alerts determined to be leak s
}

type JWTPayload ΒΆ

type JWTPayload struct {
	Exp    int      `json:"exp"`
	Iat    int      `json:"iat"`
	Iss    string   `json:"iss"`
	Scope  []string `json:"scope"`
	Sub    string   `json:"sub"`
	Type   string   `json:"type"`
	UserID int      `json:"user_id"`
}

type Location ΒΆ

type Location struct {
	ID              int    `json:"id"`
	UserID          int    `json:"user_id"`
	Name            string `json:"name"`
	PrimaryLocation bool   `json:"primary_location"`
	Address         string `json:"address"`
	Address2        string `json:"address_2"`
	City            string `json:"city"`
	State           string `json:"state"`
	PostalCode      string `json:"postal_code"`
	Country         string `json:"country"`
	TZ              string `json:"tz"`
	Installation    string `json:"installation"`
	InsurerID       int    `json:"insurer_id"`
	BuildingType    string `json:"building_type"`
	AwayMode        bool   `json:"away_mode"`
}

type LocationPatch ΒΆ

type LocationPatch struct {
	AwayMode bool `json:"away_mode"`
}

type LocationResponse ΒΆ

type LocationResponse struct {
	APIResponseEnvelope
	Data []Location `json:"data"`
}

type LocationsResponse ΒΆ

type LocationsResponse struct {
	APIResponseEnvelope
	Data []Location `json:"data"`
}

type Notification ΒΆ

type Notification struct {
	ID              int    `json:"id"`
	DeviceID        string `json:"device_id"`
	UserID          int    `json:"user_id"`
	Type            int    `json:"type"`
	Message         string `json:"message"`
	CreatedDatetime string `json:"created_datetime"`
	Title           string `json:"title"`
	Read            bool   `json:"read"`
	Extra           string `json:"extra"`
}

type NotificationsResponse ΒΆ

type NotificationsResponse struct {
	APIResponseEnvelope
	Data []Notification `json:"data"`
}

type Pagination ΒΆ

type Pagination struct {
	Next string `json:"next"`
	Prev string `json:"prev"`
}

type QueryUsageRequestBody ΒΆ

type QueryUsageRequestBody struct {
	RequestID       string   `json:"request_id"`
	Bucket          string   `json:"bucket"`
	SinceDatetime   string   `json:"since_datetime,omitempty"`
	UntilDatetime   string   `json:"until_datetime,omitempty"`
	GroupMultiplier string   `json:"group_multiplier,omitempty"`
	Operation       string   `json:"operation,omitempty"`
	SortDirection   string   `json:"sort_direction,omitempty"`
	Units           string   `json:"units,omitempty"`
	Types           []string `json:"types,omitempty"`
}

type QueryUsageResponse ΒΆ

type QueryUsageResponse struct {
	APIResponseEnvelope
	Data []UsageQuery `json:"data"`
}

type Subscription ΒΆ

type Subscription struct {
	ID                int    `json:"id"`
	UserID            int    `json:"user_id"`
	AlertType         string `json:"alert_type"`
	AlertInfo         string `json:"alert_info"`
	DeviceID          string `json:"device_id"`
	NotificationTypes int    `json:"notification_types"`
	CreatedDatetime   string `json:"created_datetime"`
	UpdatedDatetime   string `json:"updated_datetime"`
}

type SubscriptionResponse ΒΆ

type SubscriptionResponse struct {
	APIResponseEnvelope
	Data Subscription `json:"data"`
}

type SubscriptionsResponse ΒΆ

type SubscriptionsResponse struct {
	APIResponseEnvelopePagination
	Data []Subscription `json:"data"`
}

type Token ΒΆ

type Token struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresIn    int    `json:"expires_in"`
	TokenType    string `json:"token_type"`
}

type TokenResponse ΒΆ

type TokenResponse struct {
	APIResponseEnvelope
	Data []Token `json:"data"`
}

type UsageAlert ΒΆ

type UsageAlert struct {
	ID                int             `json:"id"`
	DeviceID          string          `json:"device_id"`
	TriggeredDatetime string          `json:"triggered_datetime"`
	FlumeLeak         bool            `json:"flume_leak"`
	Query             UsageAlertQuery `json:"query"`
	EventRuleName     string          `json:"event_rule_name"`
}

type UsageAlertQuery ΒΆ

type UsageAlertQuery struct {
	RequestID     string   `json:"request_id"`
	SinceDatetime string   `json:"since_datetime"`
	UntilDatetime string   `json:"until_datetime"`
	TZ            string   `json:"tz"`
	Bucket        string   `json:"bucket"`
	DeviceID      []string `json:"device_id"`
}

type UsageAlertRule ΒΆ

type UsageAlertRule struct {
	ID        string  `json:"id"`
	Name      string  `json:"name"`
	Enabled   bool    `json:"enabled"`
	Threshold float64 `json:"threshold"`
	Unit      string  `json:"unit"`
}

type UsageAlertRuleResponse ΒΆ

type UsageAlertRuleResponse struct {
	APIResponseEnvelope
	Data []UsageAlertRule `json:"data"`
}

type UsageAlertRulesResponse ΒΆ

type UsageAlertRulesResponse struct {
	APIResponseEnvelope
	Data []UsageAlertRule `json:"data"`
}

type UsageAlertsResponse ΒΆ

type UsageAlertsResponse struct {
	APIResponseEnvelope
	Data []UsageAlert `json:"data"`
}

type UsageQuery ΒΆ

type UsageQuery struct {
	Value    int    `json:"value"`
	Datetime string `json:"datetime"`
}

type User ΒΆ

type User struct {
	ID           int    `json:"id"`
	EmailAddress string `json:"email_address"`
	FirstName    string `json:"first_name"`
	LastName     string `json:"last_name"`
	Phone        string `json:"phone"`
	Status       string `json:"status"`
	Type         string `json:"type"`
}

type UserResponse ΒΆ

type UserResponse struct {
	APIResponseEnvelope
	Data []User `json:"data"`
}

Jump to

Keyboard shortcuts

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