make_post_sell/docs/make-offer.md

Make-an-Offer Mode (MPS-21)

Buyer proposes a price for any product in pricing_mode=3 or 4. Seller counters, accepts, or declines. Auto-accept and auto-decline thresholds filter lowballs and instantly close high offers without queueing.

State Machine

            ┌─────────┐
buyer       │  open   │
opens   →   └────┬────┘
                 │
                 ▼
            ┌─────────┐
            │ pending │ ◄─────────┐
            └────┬────┘           │
       ┌─────────┼─────────┐      │
       ▼         ▼         ▼      │ counter
  accepted  countered   declined  │ flips party
            ↓                     │
        (round_count++)           │
            └─────────────────────┘

terminal: accepted, declined, expired, withdrawn, paid

state	description
0 pending	open offer awaiting current_party action
1 accepted	terminal; cart line item created at agreed amount
2 countered	counter active (still pending to other party)
3 declined	terminal; rejected
4 expired	terminal; auto-expired past expires_timestamp
5 withdrawn	terminal; buyer pulled the offer
6 paid	terminal; cart payment succeeded

current_party flips between BUYER (0) and SELLER (1) on each counter; round_count caps at Shop.offer_max_rounds (default 3).

Models

• MpsOffer — one row per negotiation (product, shop, buyer, current_amount, current_party, state, expires_timestamp, round_count, buyer_message, seller_message, paid_timestamp).
• MpsOfferEvent — audit log; one row per action (open / counter / accept / decline / withdraw / expire / pay) with actor_user_id.
• MpsCartOffer — cart-side association so checkout pays the agreed amount instead of Product.price_in_cents.

Shop Settings (form_section: offer-settings)

field	default	purpose
offer_enabled	False	shop master toggle
offer_min_in_cents	NULL	reject offers below this floor (silent)
offer_auto_accept_threshold_pct	95	offer ≥ N% of list → auto-accept
offer_auto_decline_threshold_pct	50	offer < N% of list → auto-decline
offer_expiration_hours	168 (7d)	how long an offer stays open
offer_max_rounds	3	counter cap before forcing accept/decline
offer_min_buyer_account_age_hours	0	anti-spam (default open)

Per-product override: Product.allow_offers (Boolean, nullable). NULL inherits shop setting; True/False overrides.

Logic (lib/offer.py)

Pure validators:

• validate_actor_turn — actor's party must match offer.current_party; terminal-state offers reject all actions.
• validate_round_cap — rejects when round_count >= max_rounds (forces accept/decline at the cap).
• validate_floor — silent reject below Shop.offer_min_in_cents.
• auto_resolve_open — classifies a new offer as accept / decline / queue using shop's threshold percentages; list_price=0 always queues.

Orchestrators (write MpsOfferEvent rows for audit):

• open_offer — writes offer + OPEN event; applies auto-accept / auto-decline thresholds before queuing seller.
• counter_offer — flips current_party, increments round_count, sets state COUNTERED, persists actor's message.
• accept_offer — terminal; caller's responsibility to write a cart line item at offer.current_amount_in_cents.
• decline_offer — terminal.
• withdraw_offer — terminal; buyer-only (caller validates identity).
• expire_offer — idempotent system action; flips non-terminal offers past expires_timestamp to EXPIRED.
• mark_paid — cart-success hook; ACCEPTED → PAID; raises if not in ACCEPTED state.

Self-offer (buyer == seller) blocking is the view layer's job (same pattern as auctions).

Tick (scripts/offer_tick.py)

Scans non-terminal offers (PENDING / COUNTERED) past expires_timestamp and calls expire_offer on each. Idempotent.

Recommended cron: every 15 minutes — offers expire at hour granularity so coarse polling is enough.

Routes

POST /p/{product_id}/offer    open new offer (login required)
GET  /o/{offer_id}            offer detail page (buyer + seller only)
POST /o/{offer_id}/counter    counter the current amount
POST /o/{offer_id}/accept     accept current amount (terminal)
POST /o/{offer_id}/decline    decline current amount (terminal)
POST /o/{offer_id}/withdraw   buyer-only terminal pull
POST /o/{offer_id}/checkout   buyer pays accepted offer
GET  /s/{shop_id}/offers      operator inbox of all offers for the shop
GET  /o/{offer_id}/events     bounded SSE feed of the offer's state (buyer/seller only)

Live updates (bounded SSE)

/o/{offer_id}/events is a text/event-stream that polls the offer row every ~1.5s, emits a data: {json} frame on connect and whenever the state-machine state changes, sends a heartbeat comment, then closes after ~25s — the browser EventSource reconnects. This caps the worker-thread hold per client (uWSGI is sync, ~16 threads; a truly long-lived SSE would starve the pool). Shared helper: lib/sse.py (sse_response / event_stream). Timings are settings (app.sse.hold_seconds, app.sse.poll_interval_seconds; test.ini sets them tiny). The generator uses its own short-lived DB session per poll (not request.dbsession, which pyramid_tm has already closed by then). offer.js opens the EventSource on the offer page and reload()s on a state change (the whole page layout depends on state/can_act). Auctions have the same: /a/{auction_id}/events (public) + auction.js calls applyState() on each frame.

offer_open is registered before the product_slug catch-all so /p/{id}/offer is not shadowed.

Operator inbox (/s/{shop_id}/offers)

views/offer.py:shop_offers (@shop_editor_required) lists every offer for the shop — open (pending/countered) first, sorted by last action, then terminal offers — in shop_offers.j2. Each row links to /o/{id} and to the buyer's profile (/profile/{handle}?shop={shop_id}). Reachable from /actions/view via the "🤝 Offers" button (shown when shop.offer_enabled). Incoming offers still email the shop owners (send_offer_received_email); this inbox is the in-app counterpart.

Identity / privacy

Offer history and the offer page show the buyer's display name (User.display_name, which is the public name handle — full_name is private) linked to /profile/{handle}, never the email. The profile page reveals the email only to the user themselves, or to a shop owner/editor viewing in that shop's context (?shop={shop_id}) when the profile user has actually transacted there (an offer or an invoice) — see views/user.py:user_profile. _serialize_offer carries buyer_name / buyer_handle and per-event actor_name / actor_handle / actor_id (no email).

Capability-driven presentation

Every POST route works as a plain browser form submit: the server flashes a status message and 302-redirects to /o/{offer_id} (or back to the product page on error). When JS is available, static/js/offer.js intercepts the submit, posts with X-Requested-With: XMLHttpRequest, and the same handlers return JSON instead of redirecting — the JS then navigates to /o/{offer_id} without a full reload of the originating page. The no-JS path is the source of truth; JSON is an enhancement. Functional coverage: TestOfferRoutes drives the JSON path, TestOfferNoJsFallback the plain-POST path.

offer.j2 also renders a state-aware notice (.offer-state-notice, styled via the .alert variants) above the action forms — declined / withdrawn / expired / accepted (+ pay-now hint for the buyer) / your-turn / waiting — so the viewer always understands the offer's state without relying on a flash message that a JS redirect would skip. The booleans come from _serialize_offer (is_declined, is_withdrawn, is_expired, is_accepted, is_paid, plus can_act / is_open).

Cart Integration

When cart.cart_offers has one row, cart.total_price_in_cents short-circuits to offer.current_amount_in_cents + handling + gift-card-purchases. After standard cart payment success, _finalize_auction_offer_state calls lib/offer.mark_paid which flips state=PAID and writes the OFFER_EVENT_PAY audit row.

Email Notifications

• OFFER_RECEIVED — sent to all shop owners when a new pending offer arrives (sent from offer_open view; auto-accept and auto-decline paths use different emails).
• OFFER_ACCEPTED — sent to the buyer when the seller (or buyer themselves) accepts the current amount.

Decline / counter / expire emails are not yet sent (deferred — same constraint as auction tick-driven emails: cron has no request).

Testing

5 model state helpers + 12 lib pure-function unit tests + 10 lib integration tests + 12 view functional tests + 9 form section functional tests + 13 cart integration tests + 4 tick tests + 4 email tests = 69 net new tests for MPS-21 (some shared with MPS-20 in cart integration).