Skip to content

Commit

Permalink
docs: more conten
Browse files Browse the repository at this point in the history
  • Loading branch information
karl-cardenas-coding committed Jul 6, 2024
1 parent 9dcb9b3 commit c00835d
Show file tree
Hide file tree
Showing 4 changed files with 126 additions and 11 deletions.
57 changes: 49 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,27 +11,68 @@ A tool for gathering and retaining your own Whoop data.

## Overview

MyWhoop is a tool intended to help you take ownership of your Whoop data. You can use MyWhoop to interfact with your own data in different ways than what Whoop may offer or intend. MyWhoop is designed to be a simple and easy to use tool that can be run on your own machine or server. It supports the following features:
MyWhoop is a tool intended to help you take ownership of your Whoop data. You can use MyWhoop to interface with your own data in different ways than what Whoop may offer or intend. MyWhoop is designed to be a simple and easy to use and designed to be ran on your own machine or server. It supports the following features:

- 🔐 **Login**: A simple interface to login into Whoop and save your authentication token locally. The token is required for interacting with the Whoop API.
- 🔐 **Login**: A simple interface to login into the Whoop devloper portal and save an authentication token locally. The token is required for interacting with the Whoop API.
- 🗄️ **Server**: Automatically download your Whoop data daily and save it to a local file or export it to a remote location.
- 📬 **Notifications**: Receive notifications when new data is available or when an error occurs.
- 💾 **Data Export**: Export your Whoop data to a remote location such as an S3 bucket.
-

## Get Started 🚀

Please check out the [Getting Started](/docs/get-started.md) guide to get started with MyWhoop.


```shell
export WHOOP_CLIENT_ID=<your client id>
export WHOOP_CLIENT_SECRET=<your client
docker run -p 8080:8080 \
-e WHOOP_CLIENT_ID=$WHOOP_CLIENT_ID -e WHOOP_CLIENT_SECRET=$WHOOP_CLIENT_SECRET \
ghcr.io/karl-cardenas-coding/mywhoop:v1.0.0 login -n
## Commands

MyWhoop supports the following commands and global flags:

- [Dump](#dump) - Download your Whoop data and save it to a local file.
- [Login](#login) - Authenticate with the Whoop API and save the authentication token locally.
- [Help](#help) - Display help information for MyWhoop.
- [Server](#server) - Automatically download your Whoop data daily and save it to a local file or export it to a remote location.
- [Version](#version) - Display the version of MyWhoop.


#### Global Flags

| Flag | Description | Required | Default |
|---|----|---|---|
| `--config` | The file path to the MyWhoop configuration file. | No | `~/.mywhoop.yaml` |
| `--credentials` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. | No | `token.json` |
| `--debug` | Enable debug logging. | No | False |


> [!IMPORTANT]
> For more information on the MyWhoop configuration file, refer to the [Configuration Reference](./docs/configuration_reference.md) section.


### Dump

The dump command is used to download your Whoop data and save it to a local file. For more advanced configurations, use a Mywhoop configuration file. Refer to the [Configuration Reference](./docs/configuration_reference.md) section for more information.

```bash
mywhoop dump
```


### Login

The login command is used to authenticate with the Whoop API and save the authentication token locally. The command will standup a local HTTP server to handle the OAuth2 handshake with the Whoop API and save the token to a local file.

```bash
mywhoop login
```

| Flag | Description | Required | Default |
|---|----|---|---|
| `--no-auto-open` | By default, the login command will automatically open a browser window to the Whoop login page. Use this flag to disable this behavior. | No | False |
| `--port` | The port to use for the local HTTP server. | No | `8080` |
| `--redirect-url` | The redirect URL to use for the OAuth2 handshake. | No | `http://localhost:8080/redirect`. |




## Environment Variables
Expand Down
2 changes: 1 addition & 1 deletion cmd/login.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ var (
)

func init() {
loginCmd.PersistentFlags().BoolVarP(&noAutoOpenBrowser, "no-auto", "n", false, "Do not automatically open the browser to authenticate with the Whoop API. ")
loginCmd.PersistentFlags().BoolVarP(&noAutoOpenBrowser, "no-auto-open", "n", false, "Do not automatically open the browser to authenticate with the Whoop API. ")
loginCmd.PersistentFlags().StringVarP(&redirectURL, "redirect-url", "r", "/redirect", "The URL path to redirect to after authenticating with the Whoop API. Default is path is /redirect.")
loginCmd.PersistentFlags().StringVarP(&port, "port", "p", "8080", "The port to listen on. Default is 8080.")
rootCmd.AddCommand(loginCmd)
Expand Down
74 changes: 74 additions & 0 deletions docs/configuration_reference.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Configuration Reference

The MyWhoop configuration file is used to configure the behavior of MyWhoop and enable advanced features. The configuration file is a YAML file that is located at `~/.mywhoop.yaml` by default. The configuration file can be overridden by using the `--config` flag when issuing MyWhoop commands.


## Export

The export section of the configuration file is used to configure the data export feature of MyWhoop. The export feature allows you to export your Whoop data to a remote location such as an S3 bucket. The following fields are available for configuration:

| Field | Description | Required | Default |
|---|----|---|---|
| `method` | The export method to use. Allowed values are `file` and `s3`. | Yes | |
| `fileExport` | The file export configuration. Required if `method` is `file`. | No | |
| `s3Export` | The S3 export configuration. Required if `method` is `s3`. | No | |


### File Export

Local file export accepts the following fields.

| Field | Description | Required | Default |
|---|----|---|---|
| `fileName` | The name of the file to export. | Yes | `user` |
| `filePath` | The path to save the file. By default, a data folder is created in the immediate folder. | Yes | `data/` |
| `fileType` | The file type to save the file as. Allowed values are `json`. | Yes | `json` |
| `fileNamePrefix` | The prefix to add to the file name. In server mode, the data is automatically inserted as a prefix. | No | |
| `serverMode` | Ensures the file name is unique and contains a timestamp. Ensures behaviors match server mode. | No | `false` |

```yaml
export:
method: file
fileExport:
fileName: "user"
filePath: "app/"
fileType: "json"
fileNamePrefix: ""
```
### S3 Export
S3 export accepts the following fields.
| Field | Description | Required | Default |
|---|----|---|---|
| `bucket` | The S3 bucket to export the data to. | Yes | |
| `region` | The AWS region to use. | Yes | |
| `profile` | The AWS profile to use. | No | |
| `fileConfig` | The file configuration for the S3 export. Refer to the [file export configuration](#configuration-reference) for more information. | Yes | |


```yaml
export:
method: s3
awsS3:
region: "us-east-1"
bucket: "my-example-bucket"
fileConfig:
fileName: ""
fileType: "json"
fileNamePrefix: ""
serverMode: true
```
## Credentials

The credentials section of the configuration file is used to configure where the Whoop authentication token is stored or where to find it. The following fields are available for configuration:

| Field | Description | Required | Default |
|---|----|---|---|
| `credentialsFile` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. By default, MyWhoop looks for a token file in the local directory. | No | `token.json` |

```yaml
credentials:
credentialsFile: "/opt/mywhoop/token.json"
```
4 changes: 2 additions & 2 deletions docs/get-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ The following steps will guide you through the process of setting up MyWhoop on
| Scopes | The scopes required for your application. | Yes | `read:recovery, read:cycles,read:sleep, read:workout, read:profile, read:body_measurement` |
| Webhook URL| The URL for the webhook endpoint. | No | - |

> [!NOTE]
> The redirect URIs are required for the Whoop authentication flow. Use the values `http://localhost:8080/redirect, https://localhost:8080/` as the redirect UTLs. You can change the port number if you are using a different port.
> [!NOTE]
> The redirect URIs are required for the Whoop authentication flow. Use the values `http://localhost:8080/redirect, https://localhost:8080/` as the redirect UTLs. You can change the port number if you are using a different port.
![A view of the application create page](../static/images/tutorial_1.png)

Expand Down

0 comments on commit c00835d

Please sign in to comment.