Torn Vault Tracker
-Track vault balances for shared private island vaults in [Torn City](https://torn.com/).
+
+
+[
](https://github.com/SamKirkland/FTP-Deploy-Action)
+
+A web-based tracking system for monitoring shared vault transactions in the [Torn City MMORPG](https://torn.com/).
## Description
-Uses the [Torn API](https://www.torn.com/api.html) to pul the most recent vault transactions for you and your spouse. Note that in order to access the "Log" endpoint, the keys used must be created with Full Access permissions.
+This tool automatically tracks deposits and withdrawals from your Torn City private island vault using the official Torn API. It provides real-time balance tracking, available vault space calculations, and a transaction history display for multiple users.
-## Getting Started
+Key Features:
-### Dependencies
+- 🕒 Automatic transaction synchronization via Torn API
+- 💰 Real-time balance calculations (individual & combined)
+- 📊 Color-coded transaction history (green deposits/red withdrawals)
+- 🛡️ Secure API key management
+- 📈 Vault space monitoring with individual user shares
+- 💾 SQLite database for persistent storage
-* Any reasonable LAMP stack (developed on Ubuntu 20.04 with Apache and PHP 8.1.10)
+## Features
-### Installing
+### Core Functionality
-* Create folder in your server's web root, for example, 'tvt'.
-* Upload/clone this repo into your folder.
-* Edit `functions.php` to add API keys and Torn user names for you and your spouse.
-* Edit `vault.csv` to set initial balances for each user (see notes below).
-* Open the tracker in any web browser.
-* Style as you see fit in `style.css` (Optional, but if you make something cool, let me know!).
+- Automated API polling for vault transaction logs
+- Duplicate transaction prevention
+- Responsive HTML/CSS interface
+- Error handling for API failures and database issues
+- Automatic database schema creation and history population
-### Initial vault balance(s)
-Currently, there's no way to get past vault transactions via the API. If you're starting new, you can use the vault balance before your spouse adds their first deposit. For existing vaults, you'll need to figure out the balances the hard way. Once you have the balances, put them into the `vault.csv` with the proper user names. The timestamp field doesn't matter, and can be left at the current value.
+### Financial Tracking
-### Automating transaction updates
+- Individual user balances
+- Total vault balance calculation
+- Remaining vault space tracking (500M per user / 1B total)
+- Historical transaction records with timestamps
-I recommend using an external site monitoring service such as [cronitor.io](https://cronitor.io) set to check the URL of your server. A check rate of 15 minutes should be more than enough, since you can always force a refresh by simply opening the site in your browser.
+## Installation
-## Authors
+### Requirements
-Keith Solomon / [ZarathosX75](https://www.torn.com/profiles.php?XID=2606457) on [Torn](https://torn.com/)
+- Web server with PHP 8.1+
+- SQLite3 extension enabled
+- Write permissions for web server user
-## Version History
+> [!NOTE]
+> If you need hosting, I recommend [InfinityFree](https://www.infinityfree.com/). They have a robust free hosting package that has everything you need to run this project (I run my personal copy of this project on their service).
-* 0.1
- * Initial Release
+### Setup Steps
+
+1. Upload the project files to your web hosting. You can do this with an FTP client or by using `git` directly on the server (if your host supports it).
+ - To use `git`: Clone repository to web directory (the command as written will put all files in a `tvt` directory):
+
+ ```bash
+ git clone https://github.com/yourusername/tvt.git
+ ```
+
+2. Open `config.php` and configure the API keys and other settings.
+3. Access the project in your web browser to initialize the database and start tracking transactions. The first run will create the database and import the vault transactions for both users.
+
+Depending on the number of transactions, this may take some time (my dev install took about 25 seconds to pull in ~2,100 transactions). The browser will refresh when the process is complete.
+
+### Configuration
+
+ > [!IMPORTANT]
+ > API keys **must** have "Full Access" permissions to access `log` endpoints.
+
+Edit `config.php` to set up API access:
+
+- `username1` and `username2` should be changed to your usernames.
+
+ ```php
+ const USER_KEYS = [
+ 'username1' => 'your_api_key_here',
+ 'username2' => 'partner_api_key_here'
+ ];
+ ```
+
+- If you want to change the number of rows per page in the transactions table (default is 15), change the `ROWS_PER_PAGE` constant
+
+## Usage
+
+Access the tracker through your web browser after setup and configuration:
+
+- Transactions will automatically sync on page load going forward
+- Balance calculations update in real-time
+- Recent transactions display in chronological order
+
+### Contribution
+
+We welcome contributions! Please follow these guidelines:
+
+- Fork the repository
+- Create feature branch (git checkout -b feature/improvement)
+- Follow existing PHP coding standards
+- Test changes thoroughly
+- Submit a pull request
+
+### Credits
+
+Primary Author: [Keith Solomon](https://KeithSolomon.net)
+(_[ZarathosX75](https://www.torn.com/profiles.php?XID=2606457) in Torn City_)
+
+### Acknowledgements
+
+- [Torn City API documentation](https://www.torn.com/api.html)
+- [Torn City API Development Forum](https://www.torn.com/forums.php?p=forums&f=63&b=0&a=0)
+- [Roboto font by Christian Robertson](https://fonts.google.com/specimen/Roboto)
+
+> [!IMPORTANT]
+> **Disclaimer:** This project is not affiliated with or endorsed by Torn City
diff --git a/config.php b/config.php
new file mode 100644
index 0000000..8802734
--- /dev/null
+++ b/config.php
@@ -0,0 +1,16 @@
+ 'y2ypLEEIOweEXC7x',
+ 'symos' => 'lne9TZLuqvFXtK3V'
+];
+
+// Number of rows per page
+define('ROWS_PER_PAGE', 25);
diff --git a/data/.gitkeep b/data/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/favicon.png b/favicon.png
new file mode 100644
index 0000000..5562a49
Binary files /dev/null and b/favicon.png differ
diff --git a/functions.php b/functions.php
index 3318ae7..f0b6468 100644
--- a/functions.php
+++ b/functions.php
@@ -1,229 +1,199 @@
setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
-$lines = file('vault.csv', FILE_IGNORE_NEW_LINES);
-
-foreach ($lines as $key => $value) {
- $csv[$key] = str_getcsv($value);
-}
-
-// Get user log entries.
-$user1Txn = getLog(USER1_NAME, $csv);
-$user2Txn = getLog(USER2_NAME, $csv);
-
-// Merge user arrays into transaction array
-$txnVault = array_merge($user1Txn, $user2Txn);
-
-// Build array of entries not already in the CSV
-foreach ($txnVault as $key => $value) {
- $csvComp = searchForId($value['timestamp'], $csv);
-
- if (!$csvComp) {
- $csvVault[] = $value;
- }
-}
-
-// Store new trasnactions in CSV
-foreach ($csvVault as $fields) {
- fputcsv($fp, $fields);
-}
-
-fclose($fp);
-
-// searchForID(): Serach CSV array for timestamp ID
-function searchForId($id, $array) {
- foreach ($array as $key => $val) {
- if ($val[1] == $id) {
- return true;
+ $pdo->exec($createTableSQL);
+ } catch (PDOException $e) {
+ die("Database connection failed: " . $e->getMessage());
}
}
- return false;
+ return $pdo;
}
-// formatMoney(): Format raw transaction vaule to display as money
-// cents: 0=never, 1=if needed, 2=always
-function formatMoney($number, $cents = 1) {
- if (is_numeric($number)) {
- if (!$number) {
- $money = ($cents == 2 ? '0.00' : '0');
- } else {
- if (floor($number) == $number) {
- $money = number_format($number, ($cents == 2 ? 2 : 0));
- } else {
- $money = number_format(round($number, 2), ($cents == 0 ? 0 : 2));
- }
+/** Pulls and stores all vault transaction logs for a user from the Torn API.
+ *
+ * This function retrieves all transaction logs related to vault deposits and
+ * withdrawals for a specified user. It continues fetching logs until no more
+ * entries are available, and stores each entry in the database. Each log entry
+ * is uniquely identified by its ID and includes details such as timestamp,
+ * description, and amount. The function requires the user's API key to
+ * authenticate requests to the Torn API.
+ *
+ * @param string $user The user whose transaction logs are to be retrieved and stored.
+ */
+function firstRun($user) {
+ $apiKey = USER_KEYS[$user];
+
+ $pdo = getDatabaseConnection();
+
+ $to = time();
+
+ do {
+ $url = "https://api.torn.com/v2/user?selections=log&log=5850,5851&to=$to";
+ $ch = curl_init($url);
+
+ curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+ curl_setopt($ch, CURLOPT_HTTPHEADER, [
+ 'accept: application/json',
+ "Authorization: ApiKey $apiKey"
+ ]);
+
+ $response = curl_exec($ch);
+
+ curl_close($ch);
+
+ $data = json_decode($response, true);
+
+ if (empty($data['log'])) { break; }
+
+ foreach ($data['log'] as $key => $entry) {
+ $description = $entry['title'];
+ $timestamp = $entry['timestamp'];
+ $amount = isset($entry['data']['deposited']) ? $entry['data']['deposited'] : -$entry['data']['withdrawn'];
+
+ $stmt = $pdo->prepare('INSERT INTO vault (ID, user, timestamp, description, amount) VALUES (:id, :user, :timestamp, :description, :amount)');
+
+ $stmt->bindValue(':id', $key);
+ $stmt->bindValue(':user', $user);
+ $stmt->bindValue(':timestamp', $timestamp);
+ $stmt->bindValue(':description', $description);
+ $stmt->bindValue(':amount', $amount);
+
+ $stmt->execute();
}
- if (substr($number,0,1) == '-') {
- $money = ltrim($money, '-');
- $sign = '-$';
- } else {
- $sign = '$';
- }
-
- return $sign.$money;
- }
+ $to = end($data['log'])['timestamp'];
+ } while (true);
}
-// getLog(): Get log entries for user. Returns array.
-function getLog($user, $csv) {
- $tornURL = 'https://api.torn.com/user/?selections=log&key=';
- $i = 0;
+/** Retrieves the user's log entries from the Torn API
+ *
+ * @param string $user The user to retrieve the log for
+ * @param boolean $debug Whether to output debug information (default: false)
+ *
+ * @throws Exception If the user does not have an API key configured,
+ * if the API call fails, or if the log data is invalid
+ */
+function getLog($user, $debug = false) {
+ $pdo = getDatabaseConnection();
- if ($user == USER1_NAME) {
- $usrKey = USER1_KEY;
- $user = USER1_NAME;
+ ensureUserHasApiKey($user);
+
+ $stmt = $pdo->query("SELECT MAX(timestamp) AS max_timestamp FROM vault WHERE user = '$user'");
+ $row = $stmt->fetch(PDO::FETCH_ASSOC);
+
+ $from = $row['max_timestamp'];
+ $to = time();
+
+ $apiKey = USER_KEYS[$user];
+ $apiEndpoint = "https://api.torn.com/user/?selections=log&log=5850,5851&to=$to&from=$from&key=$apiKey";
+
+ $responseData = executeApiCall($apiEndpoint);
+ validateApiResponse($responseData);
+
+ $checkStmt = prepareCheckStatement($pdo);
+ $insertStmt = prepareInsertStatement($pdo);
+
+ processLogEntries($responseData['log'], $user, $checkStmt, $insertStmt, $debug);
+}
+
+/** Generate the current balance for a user or all users
+ *
+ * @param string $name (optional) The user to get the balance for. If not provided, all users' balances will be added.
+ *
+ * @return string The balance as a formatted string
+ */
+function generateBalance($name=null) {
+ $balance = vaultLoop($name);
+
+ return number_format($balance, 0); // Format the balance as an integer
+}
+
+/** Calculate the available vault space for a user or all users.
+ *
+ * This function calculates the remaining space in the vault based on the
+ * transactions for a specific user or all users. If a user is specified,
+ * the available space is calculated against a limit of 500,000,000.
+ * If no user is specified, the available space is calculated against a
+ * total vault limit of 1,000,000,000.
+ *
+ * @param string|null $name (optional) The user to calculate the vault space for.
+ * If not provided, calculates for all users.
+ *
+ * @return string The available vault space as a formatted string.
+ */
+
+function getSpace($name=null) {
+ $space = vaultLoop($name);
+
+ if ($name === null) {
+ $space = 1000000000 - $space;
} else {
- $usrKey = USER2_KEY;
- $user = USER2_NAME;
+ $space = 500000000 - $space;
}
- $usrURL = $tornURL . $usrKey;
- $usrLog = json_decode(file_get_contents($usrURL));
- $usrData = $usrLog->log;
- $usrVault = [];
+ return number_format($space, 0); // Format the balance as an integer
+}
- foreach ($usrData as $entry) {
- if ($entry->log == 5851) {
- $usrVault[$i]['user'] = $user;
- $usrVault[$i]['timestamp'] = $entry->timestamp;
- $usrVault[$i]['operation'] = $entry->title;
- $usrVault[$i]['amount'] = '-'.$entry->data->withdrawn;
- } elseif ($entry->log == 5850) {
- $usrVault[$i]['user'] = $user;
- $usrVault[$i]['timestamp'] = $entry->timestamp;
- $usrVault[$i]['operation'] = $entry->title;
- $usrVault[$i]['amount'] = $entry->data->deposited;
+/** Builds an HTML table of all transactions in the vault
+ *
+ * Loops over all records in the vault and builds a table of the user, timestamp,
+ * description and amount of each transaction. Amounts are formatted as integers.
+ *
+ * @return void
+ */
+function buildTable () {
+ $records = fetchVaultRecords();
+
+ foreach ($records as $entry) {
+ $user = $entry['user'];
+ $timestamp = $entry['timestamp'];
+ $description = $entry['description'];
+ $amount = $entry['amount'];
+ $sign = getSign($amount);
+
+ if ($description == 'Vault withdraw') {
+ $class = 'debit';
+ $amount = substr($amount, 1); // Remove the negative sign
} else {
- continue;
+ $class = 'credit';
}
- $i++;
+ $amount = number_format($amount, 0); // Format the amount as an integer
+
+ echo 'User | ';
- $output .= ' Timestamp | ';
- $output .= ' Operation | ';
- $output .= ' Amount | ';
- $output .= ' ';
-
- $output .= ' ';
-
- $csv = array_reverse($csv);
-
- foreach ($csv as $entry) {
- if ($entry[2] == 'Vault withdraw') {
- $class = 'debit';
- } else {
- $class = 'credit';
- }
-
- $output .= '
| '; - $output .= $entry[0]; // User - $output .= ' | '; - $output .= ''; - $output .= date("d/m/Y", $entry[1]); // Transaction Date - $output .= ' | '; - $output .= ''; - $output .= $entry[2]; // Transaction Type - $output .= ' | '; - $output .= ''; - $output .= formatMoney($entry[3]); // Transaction Amount - $output .= ' | '; - $output .= '
User |
+ Date / Time (TCT) |
+ Operation |
+ Amount |
+
|---|