Stockroom Phase 6 eBay Connection and Alerts Plan

Part of the Simple Agility stack. Canonical copy: ~/source/stockroom/docs/superpowers/plans/2026-10-08-stockroom-phase-6-ebay-connection-and-alerts.md (8 test-first tasks with complete code). This page mirrors the decisions for retrieval. It implements the phase 6 parts of StockroomChannelsAndSalesDesign and builds on StockroomPhase5ListingsAndSalesPlan. Status: built and reviewed 2026-10-09, not yet deployed or connected.

• Executed task by task (commits 9db2a70..bdf3d36), with a review per task and a final whole-phase review whose fix wave was verified.
• The backend gates pass, including the end-to-end EbaySyncIT, and so does the frontend gate.
• Connecting the real eBay account and a Telegram bot is the operator's step: eBay-API.md section 11 and docs/operations.md › Channels and sales.
• What was deliberately left, and the open questions, are in docs/superpowers/notes/2026-10-09-phase-5-6-review-carryover.md.

Goal

• eBay sales arrive by themselves. Every 2 minutes Stockroom reads the operator's eBay orders. A paid line becomes a sale, the item's other posts go to To delist, and a Telegram message lists them.
• eBay listings are found by SKU. Every 15 minutes Stockroom reads the active eBay listings and records each as a post by its Custom label.
• eBay listings end by themselves. A sale anywhere else ends the item's eBay listing by job. A listing still up for a sold item is ended as a safety net.
• Telegram alerts come from a bot of Stockroom's own. They cover:
  • eBay sales with posts to delete;
  • delist reminders every 30 minutes;
  • oversold items;
  • one summary per sync of new unmatched eBay sales and listings;
  • failed ends;
  • a refused eBay token.
• Unmatched eBay rows appear on the To delist page, with Link to item, Dismiss and Dismiss all.

Without the eBay refresh token, eBay works by hand exactly as in phase 5. Without the Telegram variables nothing is sent; the pages still show everything.

Architecture

• New adapter module stockroom-channels. It holds the eBay seller adapter and the Telegram adapter, with no new dependencies. The eBay adapter covers:
  • the refresh-token grant;
  • Fulfillment getOrders over REST;
  • Trading GetMyeBaySelling and EndFixedPriceItem over hardened XML.
• Core. It holds:
  • the EbaySellerAccount and Notifier ports;
  • the pure OrderLineMapper and SkuMatcher;
  • three job handlers: ebay_orders_sync, ebay_listings_sync and ebay_end_listing;
  • a durable notify job, the scheduler and the delist reminders.
• Rules kept.
  • No network call inside a database transaction.
  • The adapters never throw: an unexpected error becomes unavailable, logged by its class only.
  • No buyer data is stored or logged.

Key decisions

Topic	Decision
Connected	eBay is configured when the client id, secret and refresh token are set, and connected when configured and not refused. A refusal (invalid_grant, eBay rejecting the token, or a 403 with error 1100) is held in memory until restart. It sends one message and shows Re-connect eBay.
Orders poll	The poll reads from a stored bookmark minus 10 minutes; the first run reads the last 14 days. Each line is applied in its own transaction, oldest first. The bookmark moves only after every line is read and applied, so each line is recorded and messaged once. An unreadable line holds the bookmark but never blocks the readable ones.
SKU matching	Matching is trimmed and case-insensitive, with or without the I- label prefix. Lot members, FBA items and dissolved lots go to Unmatched eBay with the reason.
Oversold	A paid line for an item that already sold elsewhere is saved as an oversold sale with no effects, and a message is sent. Cancelling the active sale promotes the newest oversold one.
Adopting	A sale recorded by hand on eBay gets the order and line numbers when the poll finds them.
Currency	A paid line not in US dollars lands in Unmatched eBay without amounts and cannot be linked. The operator records it by hand and dismisses the row.
Ending	One ebay_end_listing job runs per post, queued after the sale commits. Already ended counts as success, and an unavailable eBay retries. A refusal leaves the post in To delist with one message. While an end job holds a post, it stays off To delist, its tile and the reminders; the pending-delists gauge still counts it.
Vanished listings	A post ends only when two complete active lists in a row both miss it: ended_on_ebay, or sold_elsewhere when it was pending. A list whose count differs from eBay's stated total is treated as incomplete and changes nothing.
Unmatched eBay	Each order line or listing gets one row, however many polls see it, and new rows are announced in one summary message per sync. A later poll never resolves a row; the operator links, dismisses or dismisses all.
Locking	A polled line locks its sale first when it has one, otherwise the item. Adopting locks the item then the sale, the reverse of a hand cancel. A simultaneous clash makes PostgreSQL abort one side, which retries or answers try again. This is accepted for one operator.
Telemetry	New counters cover sync outcomes, notifications and oversold sales, and delists gain api and sync. The gauge stockroom_ebay_sync_age_seconds lets jakemon alert when the orders sync has not succeeded for 15 minutes.

Tasks

1. Module, ports and plumbing: stockroom-channels, V026 (ebay_unmatched), the eBay and notify ports, user tokens, Notifications, the environment
2. Adapter: Fulfillment getOrders
3. Adapters: Trading listings and ends, Telegram, ChannelsConfig
4. Orders sync: SKU matching, the line mapper, oversold and promotion
5. Listings sync and ending, the scheduler, delist reminders, the sync-age gauge
6. API and end to end: eBay status, Link and Dismiss, To delist without posts an end job holds, EbaySyncIT
7. Frontend: the eBay status line, the re-connect banner and Unmatched eBay
8. Hand-over: the eBay sign-in runbook, Telegram setup, a read-only live smoke test, coverage, operator acceptance

Out of scope

• Posting through eBay's API, and eBay push notifications.
• The account-deletion notification endpoint (a follow-up if the operator's exemption no longer applies).
• The Finances API, the Amazon SP-API, any channel other than eBay, web push or email.

---

Cluster Hub: Stockroom Hub (stockroom)