ShopNotifier Technical Documentation

1. Overview
ShopNotifier centralizes every player-driven marketplace and auction feed into one plugin. It collects listings via modular crawlers, exposes intuitive GUIs for browsing and tracking deals, and offers automated alerts and inventory security to keep player economies fair.

2. Supported Integrations

• Player Shops: ShopChest, QuickShop Re-Remake, QuickShop-Hikari, EzChestShop, VillagerMarket, Shopkeepers, SignShop, ChestShop-3, DisplayShops, iShop.
• Auction Houses: GlobalMarketChest, FAuction, NexusAuctionHouse, PlayerMarket.
• Additional crawlers can be disabled per plugin to fit your server stack.

3. Installation & Setup

• Place the jar and any required dependencies (e.g. MariaDB driver when MySQL is enabled) into your server’s plugins folder.
• Start the server once to generate the default configuration.
• Edit `config.yml` to match your economy, database, and notification preferences, then reload or restart.

4. Configuration Reference

• plugins: Toggle individual crawlers. Each entry has an `enabled` flag so you can selectively integrate only the shops you run.
• mysql: Optional MariaDB/MySQL storage for listing caching. Disable if you prefer in-memory operation.
• notifications: Enable/disable the entire notification system and specific channels (`ntfy`, `discord`). The `auto` block controls timed or trigger-based scans (`interval_minutes`, `on_last_player_leave`, `on_server_start`).
• privacy.double_hide: When true, players who hide their shops cannot use global browsing commands until they re-enable visibility.
• messages: Every player-facing message can be customized. Color codes (`&a`, `&c`, etc.) and placeholders like `%ITEM%`, `%PRICE%`, `%STATE%` are supported via the internal `MessageManager` cache.
• item_security: Controls the GUI NBT protection. `enabled` toggles the security layer and `scan_interval_seconds` defines how often player inventories are checked for stolen GUI items.

5. Item Security System

• All GUI items are tagged with hidden PersistentDataContainer values through `ItemSecurityUtil`.
• `ItemSecurityManager` runs a repeating task that scans every online player. Tagged items found outside plugin GUIs are deleted on the spot.
• Admins with `shopnotifier.admin` receive instant alerts. Console logs include the player name, item type, and amount for auditing.
• If item security is disabled or the interval is zero, the scanning task never starts.

6. Command Overview

• /shopnotifier: Opens the in-game help menu.
• /shopnotifier selling [maxPrice]: Shows cross-plugin listings where players sell items. Optional price cap.
• /shopnotifier buying [maxPrice]: Displays all buy orders with optional price filtering.
• /shopnotifier craft <item>: Reveals crafting ingredients along with marketplace availability for each ingredient.
• /shopnotifier seller <player>: Views a specific seller’s inventory across every supported plugin.
• /shopnotifier track: Opens the material picker to start tracking deal alerts (requires at least one notification channel saved).
• /shopnotifier trackings: Manage tracked items, adjust price limits, or delete entries.
• /shopnotifier ntfy <channel|delete>: Store or remove an ntfy topic for personal alerts.
• /shopnotifier dc <webhook|delete>: Save or clear a Discord webhook endpoint.
• /shopnotifier hide: Toggle personal shop visibility. When hidden and `double_hide` is on, browsing commands are blocked.
• /shopnotifier notify <all|ntfy|discord> <on|off>: (Admin) Toggle notification channels globally.
• /shopnotifier forcenotify ireallyknowwhatimdoing: (Admin) Runs an immediate marketplace scan and pushes alerts.

7. Permissions
Grant or revoke access using your permission manager:

• shopnotifier.selling, shopnotifier.buying, shopnotifier.craft, shopnotifier.seller: Control browsing commands.
• shopnotifier.track, shopnotifier.ntfy, shopnotifier.dc: Allow players to manage alerts.
• shopnotifier.admin: Receives security notifications and holds overarching administrative power.
• shopnotifier.admin.notify, shopnotifier.admin.debugnotify: Required for notify and forcenotify commands.

8. GUI Features

• Marketplace GUI: Paginated view of listings with search, teleport, and info panels for source plugin, owner, price, and location.
• Track Item GUI: Filterable material list with per-item selection and price entry.
• Price Select GUI: Fine-grained price adjustment buttons (-100 to +100) and save confirmation.
• Tracking Management GUI: Overview of every tracked item, delete confirmations, and navigation.

9. Notification Workflow

• Players opt into ntfy.sh topics or Discord webhooks.
• `NotificationManager` collects deals from the configured crawlers and respects cache freshness through `CacheManager`.
• Automated scans run on timers or triggers (server start, last player exit). Admins can initiate manual scans.
• Notifications summarize affordable listings matched against each player’s tracked items.

10. Performance Notes

• Crawlers are modular and only activate if both the plugin is present and its entry is enabled in config.
• Cache layers reduce expensive marketplace scanning and control refresh rates.
• Long-running HTTP calls (ntfy.sh/Discord) execute asynchronously to keep the main thread responsive.

11. Troubleshooting

• Listings Missing: Confirm the third-party plugin is loaded and `plugins.<name>.enabled` is true. Check console for crawler initialization warnings.
• No Notifications: Ensure `notifications.enabled` and the relevant channel flags are enabled. Verify players saved their channel or webhook and that automated scans are scheduled.
• Security Alerts Triggering Frequently: Reduce `scan_interval_seconds` or disable temporarily while diagnosing. Verify no other plugin duplicates or copies ShopNotifier GUI items.
• Database Errors: Install the MariaDB JDBC driver and confirm credentials in the `mysql` block.

12. Best Practices

• Translate messages in `config.yml` so announcements fit your server’s tone.
• Use `forcenotify` during quiet hours to broadcast new deals without waiting for scheduled scans.
• Communicate security policies to players so they understand removed items are anti-theft measures.
• Set realistic notification intervals to avoid spam and ensure timely updates.