README
¶
go-butterflymx
A Go client library for interacting with the ButterflyMX API.
[!NOTE] This is an unofficial library and uses reverse-engineered API endpoints. Use at your own risk.
Coverage
- Authentication -- will not be implemented due to 2FA complexity
- Authorization
- Fetching Rails API Access Token
- Renewing Rails API Access Token
- Fetching Tenants list
- Fetching Access Points for a Tenant
- Unlocking Door
- Keychains support
- List
- Get (by ID)
- Create
- Update
- Delete
- Virtual Keys support
- List (via Keychains)
- Create (via adding to Keychain)
- Update
- Delete
Documentation
¶
Overview ¶
Package butterflymx provides a Go client for the ButterflyMX API.
Index ¶
Constants ¶
const AssumedAPITokenValidity = 5 * time.Minute
AssumedAPITokenValidity is the assumed validity duration for ButterflyMX API tokens obtained via OAuth2 exchange, as the actual validity period is unknown.
const DatestampLayout = "2006-01-02"
const TimestampLayout = "15:04"
Variables ¶
var APIDeviceInfo = map[string]any{ "locales": []string{"en"}, "platform": "android", "version": "1.56.0", }
APIDeviceInfo represents the device information sent during the OAuth2 to API token exchange.
var ErrInvalidTaggedID = errors.New("invalid TaggedID")
ErrInvalidTaggedID is returned when a TaggedID is invalid.
Functions ¶
This section is empty.
Types ¶
type APIStaticToken ¶
type APIStaticToken string
APIStaticToken represents a static ButterflyMX API token.
func (APIStaticToken) APIToken ¶
func (t APIStaticToken) APIToken(ctx context.Context, _ bool) (APIStaticToken, error)
APIToken returns the token as a string.
type APITokenSource ¶
type APITokenSource interface {
// APIToken should return a valid API token or an error.
//
// If [renew] is true, the implementation should attempt to renew the token
// even if a cached token is available. Implementations may ignore this
// parameter, and the caller must detect that the "new" token is still
// invalid.
APIToken(ctx context.Context, renew bool) (APIStaticToken, error)
}
APITokenSource is an interface for acquiring a ButterflyMX API token.
func ReuseAPITokenSource ¶
func ReuseAPITokenSource(src APITokenSource) APITokenSource
ReuseAPITokenSource returns a new APITokenSource that obeys the [renew] parameter. If [src] is already a reused token source, it is returned as-is.
type Datestamp ¶
Datestamp represents a date in year, month, day format and without a timezone.
func (Datestamp) MarshalText ¶
MarshalText implements encoding.TextMarshaler.
func (Datestamp) ToTime ¶
ToTime converts the Datestamp to a time.Time in the given timezone at midnight.
func (*Datestamp) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler.
type ID ¶
type ID int
ID is an untagged numeric ID.
func TaggedIDsToNumbers ¶
TaggedIDsToNumbers converts a slice of TaggedID to a slice of ID.
func (ID) MarshalJSON ¶
MarshalJSON implements [json.Marshaler].
func (*ID) UnmarshalJSON ¶
UnmarshalJSON implements [json.Unmarshaler].
type OAuth2Client ¶
type OAuth2Client struct {
// contains filtered or unexported fields
}
OAuth2Client consumes an OAuth2 token to exchange it for a ButterflyMX API token. This client does not interact with the main ButterflyMX API endpoints for actions like opening doors or creating keys.
It implements the APITokenSource interface.
func NewOAuth2Client ¶
func NewOAuth2Client(tokenSource oauth2.TokenSource) *OAuth2Client
NewOAuth2Client creates a new client for handling the OAuth2 to API token exchange. It takes an oauth2.TokenSource, which is expected to be fully configured and capable of providing valid OAuth2 access tokens for the ButterflyMX service.
func (*OAuth2Client) APIToken ¶
func (c *OAuth2Client) APIToken(ctx context.Context, renew bool) (APIStaticToken, error)
APIToken performs the token exchange for a new token. It always returns a new token regardless of [renew].
It first retrieves an OAuth2 access token from the client's token source, then sends it to the /denizen/v1/login endpoint. The ButterflyMX API validates the OAuth2 token and returns a Rails session token, which is required for all subsequent API interactions.
func (*OAuth2Client) APITokenSource ¶
func (c *OAuth2Client) APITokenSource() APITokenSource
APITokenSource returns an APITokenSource that provides an API token until it needs to be renewed (once [renew] is true).
type TaggedID ¶
type TaggedID struct {
Prefix string // prod
Type string // e.g., tenant, unit, building
Number ID // numeric ID
}
TaggedID is a string of type `prod-{type}-{id}`.
func NewTaggedID ¶
NewTaggedID creates a new TaggedID with the "prod" prefix.
func (TaggedID) MarshalText ¶
MarshalText implements encoding.TextMarshaler.
func (*TaggedID) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler.
type Timestamp ¶
Timestamp represents a time of day in the format TimestampLayout.
func (Timestamp) MarshalText ¶
MarshalText implements encoding.TextMarshaler.
func (Timestamp) ToTime ¶
ToTime converts the WatchTime to a time.Time on the given date using that date's timezone.
func (*Timestamp) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler.
type Weekday ¶
type Weekday string
Weekday represents a day of the week.
func (Weekday) ToTimeWeekday ¶
ToTimeWeekday converts the Weekday to time.Weekday.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
httpmock
Package httpmock provides a mock HTTP RoundTripper for testing purposes.
|
Package httpmock provides a mock HTTP RoundTripper for testing purposes. |
|
Package ptr contains helper types and functions for working with optional types as pointers.
|
Package ptr contains helper types and functions for working with optional types as pointers. |