# 📦 Wallos Fetcher

Wallos Fetcher is a command-line utility designed to retrieve and export subscription data from a self-hosted [Wallos](https://github.com/WallosApp/Wallos) instance—an open-source personal subscription tracker.

This script helps you keep track of all your recurring expenses and share that information in human-readable or machine-readable formats, making it especially useful for budgeting, personal finance planning, and digital legacy preparation for family members.

---

## ✨ Features

- 📄 **Markdown output by default** – easy to read, easy to share
- 💾 Export as **Markdown**, **CSV**, or **JSON**
- 🔍 Optionally include **full subscription details** (e.g., cycle, auto-renew, currency)
- 🗃 Output to a custom file
- 🧰 Lightweight, portable, and dependency-minimal (requires `curl` and `jq`)

---

## 🚀 Installation

```bash
git clone https://git.nickhepler.cloud/nick/wallos-fetcher.git
cd wallos-fetcher
chmod +x wallos-fetch.sh
```

> 🔧 Ensure you have `curl` and `jq` installed.

- **Ubuntu/Debian**:
  ```bash
  sudo apt install curl jq
  ```

- **macOS (Homebrew)**:
  ```bash
  brew install curl jq
  ```

---

## 🧪 Usage

```bash
./wallos-fetch.sh [options]
```

### ✅ Example Commands

| Purpose                             | Command                                                |
|-------------------------------------|---------------------------------------------------------|
| Default output as Markdown          | `./wallos-fetch.sh`                                     |
| Export as JSON                      | `./wallos-fetch.sh --json`                              |
| Export as CSV                       | `./wallos-fetch.sh --csv`                               |
| Include extended subscription data  | `./wallos-fetch.sh --full`                              |
| Custom output filename              | `./wallos-fetch.sh --output mysubs.md`                 |
| Combine options                     | `./wallos-fetch.sh --csv --full --output mysubs.csv`   |
| Show help                           | `./wallos-fetch.sh --help`                              |
| Check script version                | `./wallos-fetch.sh --version`                           |

---

## 📄 Output Formats

### 🧾 Markdown (Default)

Designed for human readability and sharing with family members.

Includes:

- A title (`# 🧾 Active Subscriptions Overview`)
- A short description for context and legacy planning
- A table of subscriptions with essential or full detail (if `--full` used)

```markdown
# 🧾 Active Subscriptions Overview

This document lists all recurring subscriptions tied to this household or individual. It includes costs, renewal dates, categories, and payment methods. This record is provided as a reference for financial planning, digital legacy management, or to assist family members in case of emergencies or estate matters.

_Last updated: 2025-04-21_

| ID | Name | Price | Next Payment | Category | Payment Method |
|----|------|-------|---------------|----------|----------------|
| 1  | Netflix | 17.99 | 2025-04-21 | Entertainment | Credit Card |
```

### 📊 CSV

Structured export for use in spreadsheets or data processing tools.

- Default fields: `id,name,price,next_payment,category_name,payment_method_name`
- `--full` option adds: `currency_id,cycle,auto_renew`, etc.

### 📦 JSON

Raw response data from the Wallos API—useful for backups or integrations.

---
## 🔐 Authentication

You can set your API key in one of two ways:

### 1. Environment Variable (Recommended)

This is the preferred and more secure method, especially for automation and scripting:

```bash
export WALLOS_API_KEY="your_api_key_here"
```

The script will automatically detect this variable and use it if `API_KEY` is not set inside the script.

### 2. Hardcoded in Script (Optional)

Open the `wallos-fetch.sh` file and manually set your API key by replacing this line:

```bash
API_KEY="${API_KEY:-$WALLOS_API_KEY}"
```

with:

```bash
API_KEY="your_api_key_here"
```

> ⚠️ Be cautious: hardcoding secrets in scripts can pose a security risk if the file is shared or version-controlled.

## 📜 License

This project is licensed under the [GNU General Public License v3.0 or later](https://www.gnu.org/licenses/gpl-3.0.html).

---

## 🤝 Contributions

Feedback, bug reports, and pull requests are welcome!  
Submit issues or improvements via your Gitea repository.

---

## ❤️ About Wallos

Wallos is an open-source personal subscription manager. Learn more or contribute to the main project here:

🔗 https://github.com/WallosApp/Wallos