Crussell/backend/handlers/webhooks/square.go

package webhooks

import (
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"database/sql"
	"encoding/base64"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"sync"

	"crussell/db"
	"crussell/handlers/payments"
)

type SquareWebhookEvent struct {
	Type       string          `json:"type"`
	EventID    string          `json:"event_id"`
	CreatedAt  string          `json:"created_at"`
	Data       json.RawMessage `json:"data"`
	LocationID string          `json:"location_id"`
}

// squareWebhookDedup is a bounded, mutex-guarded set of recently handled
// event IDs. It is a FAST-PATH cache only: the persistent source of truth is
// the square_webhook_events table (see HandleSquareWebhook). It lets a replayed
// delivery be dropped without a DB round-trip, but a restart clears it — the DB
// row is what keeps delivery at-least-once across restarts (a replay after a
// crash is re-dispatched and absorbed by the idempotent handlers, per the
// dispatch-first ordering in HandleSquareWebhook).
type squareWebhookDedup struct {
	mu    sync.Mutex
	seen  map[string]struct{}
	order []string
	max   int
}

func newSquareWebhookDedup(max int) *squareWebhookDedup {
	return &squareWebhookDedup{
		seen:  make(map[string]struct{}),
		order: make([]string, 0, max),
		max:   max,
	}
}

// has reports whether id is in the set WITHOUT recording it. Used as the
// fast-path short-circuit before the DB dedup insert.
func (d *squareWebhookDedup) has(id string) bool {
	d.mu.Lock()
	defer d.mu.Unlock()
	_, ok := d.seen[id]
	return ok
}

// register records id, reporting whether it was already present (set untouched
// on a replay, preserving insertion order). Mutex-guarded — the handler may be
// hit concurrently. Called only after the DB insert has confirmed the event's
// fate, so a failed DB write never leaves a stale entry that would drop a retry.
func (d *squareWebhookDedup) register(id string) bool {
	d.mu.Lock()
	defer d.mu.Unlock()
	if _, ok := d.seen[id]; ok {
		return true
	}
	d.seen[id] = struct{}{}
	d.order = append(d.order, id)
	if len(d.order) > d.max {
		oldest := d.order[0]
		d.order = d.order[1:]
		delete(d.seen, oldest)
	}
	return false
}

// 500 IDs far exceeds the latency payoff of the fast-path cache; the DB row
// (square_webhook_events) is the unbounded, restart-safe source of truth.
var squareWebhookEventsSeen = newSquareWebhookDedup(500)

// HandleSquareWebhook verifies and dispatches Square webhook events.
//
// Fail-closed chain: 503 when the signing key is unset, 403 on a missing/bad
// signature, 400 on malformed JSON or an empty event_id (which cannot be
// deduplicated — Square always sends one, so this is defensive). A correctly
// signed, well-formed event is deduplicated by event_id before dispatch and
// acknowledged 200.
func HandleSquareWebhook(w http.ResponseWriter, r *http.Request) {
	r.Body = http.MaxBytesReader(w, r.Body, 512*1024)
	body, err := io.ReadAll(r.Body)
	if err != nil {
		log.Printf("Failed to read webhook body: %v", err)
		http.Error(w, "request body too large or unreadable", http.StatusRequestEntityTooLarge)
		return
	}
	defer r.Body.Close()

	// Verification logic per Square spec (HMAC-SHA256, base64, notificationURL + body).
	// Production setup: set SQUARE_WEBHOOK_SIGNATURE_KEY and SQUARE_WEBHOOK_NOTIFICATION_URL
	// in env vars (see Square Developer Console → Webhooks → Subscription).
	// Reference: https://developer.squareup.com/docs/webhooks/step3validate

	// Fail closed: a missing signing key means the webhook cannot be verified,
	// so reject rather than process unauthenticated events (S-4). Square
	// always sends the signature header, so an unset key in production is a
	// misconfiguration that must not silently accept forged events.
	signingKey := os.Getenv("SQUARE_WEBHOOK_SIGNATURE_KEY")
	notificationURL := os.Getenv("SQUARE_WEBHOOK_NOTIFICATION_URL")
	if notificationURL == "" {
		notificationURL = "http://localhost:8080/webhooks/square"
	}
	if signingKey == "" {
		log.Printf("SQUARE_WEBHOOK_SIGNATURE_KEY is not set — rejecting webhook (fail-closed)")
		http.Error(w, "webhook signature verification unavailable", http.StatusServiceUnavailable)
		return
	}
	signature := r.Header.Get("x-square-hmacsha256-signature")
	if signature == "" {
		log.Printf("Missing Square webhook signature header")
		http.Error(w, "Invalid signature", http.StatusForbidden)
		return
	}
	if !verifySquareSignature(body, signature, signingKey, notificationURL) {
		log.Printf("Invalid Square webhook signature")
		http.Error(w, "Invalid signature", http.StatusForbidden)
		return
	}

	var event SquareWebhookEvent
	if err := json.Unmarshal(body, &event); err != nil {
		log.Printf("Failed to parse webhook event: %v", err)
		http.Error(w, "Invalid event", http.StatusBadRequest)
		return
	}

	// An empty event_id cannot be deduplicated. Square always sends event_id,
	// so this is defensive — but once handlers mutate state, a duplicate
	// empty-ID event would double-apply. Reject with 400 (fail-safe, no
	// dispatch, no dedup row): Square's retry policy retries on 5xx/timeouts
	// but treats 4xx as non-retryable, so the malformed event is dropped
	// without side effects.
	if event.EventID == "" {
		log.Printf("[SQUARE-WEBHOOK] Rejecting event with empty event_id (400)")
		http.Error(w, "Invalid event", http.StatusBadRequest)
		return
	}

	// Fast-path dedup: a correctly signed replay of a recently handled event is
	// dropped in memory without a DB round-trip. The persistent source of truth
	// is the square_webhook_events row committed AFTER dispatch below, so this
	// cache never hides an event whose dedup row is not yet persisted — a crash
	// before that commit simply replays the event, which the idempotent handlers
	// absorb.
	if squareWebhookEventsSeen.has(event.EventID) {
		log.Printf("[SQUARE-WEBHOOK] Duplicate event_id %s; skipping (already processed)", event.EventID)
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
		return
	}
	if db.Conn == nil {
		log.Printf("[SQUARE-WEBHOOK] DB unavailable — rejecting event_id %s (fail-closed)", event.EventID)
		http.Error(w, "webhook processing unavailable", http.StatusServiceUnavailable)
		return
	}

	log.Printf("[SQUARE-WEBHOOK] Received event: %s", event.Type)

	// Dispatch FIRST, then commit the dedup row. The handlers mutate state, so a
	// dedup row committed before dispatch would permanently drop the event on a
	// crash between the insert and the dispatch (Square's retry would be
	// 200-skipped, and dispute.created has no sweep fallback). Committing after
	// a successful dispatch keeps delivery at-least-once: on any dispatch error
	// NO dedup row is written and we return 5xx so Square retries. The handlers
	// are idempotent (status='pending'-guarded UPDATEs keyed on the Square id),
	// so a retry — or two retries dispatching concurrently — applies each state
	// change at most once and is otherwise a no-op.
	var dispatchErr error
	switch event.Type {
	case "payment.updated", "payment.created":
		dispatchErr = handlePaymentUpdated(r.Context(), event.Data)
	case "refund.updated", "refund.created":
		dispatchErr = handleRefundUpdated(event.Data)
	case "dispute.created":
		dispatchErr = handleDisputeCreated(event.Data)
	case "dispute.state.updated":
		dispatchErr = handleDisputeStateUpdated(event.Data)
	case "dispute.evidence.created", "dispute.evidence.deleted":
		dispatchErr = handleDisputeEvidence(event.Data)
	case "terminal.checkout.created", "terminal.checkout.updated":
		dispatchErr = handleTerminalCheckout(event.Data)
	default:
		log.Printf("[SQUARE-WEBHOOK] Unknown event type: %s", event.Type)
	}
	if dispatchErr != nil {
		log.Printf("[SQUARE-WEBHOOK] Event %s (%s) dispatch failed: %v — NOT recording dedup row; Square will retry", event.Type, event.EventID, dispatchErr)
		http.Error(w, "webhook processing failed", http.StatusServiceUnavailable)
		return
	}

	// Commit the dedup row AFTER successful dispatch. Fail closed on a write
	// error: without a persisted row we cannot prove the event was handled, so
	// reject and let Square retry (the retry re-dispatches idempotently and
	// retries the insert). event_id is not PII, so logging it is safe.
	tag, err := db.Conn.Exec(r.Context(),
		"INSERT INTO square_webhook_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING", event.EventID)
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to record event_id %s (dedup write failed): %v", event.EventID, err)
		http.Error(w, "webhook processing unavailable", http.StatusServiceUnavailable)
		return
	}
	// Record in the fast-path cache only after the DB write succeeds, so a
	// failed write never leaves a stale entry that would drop a retry.
	squareWebhookEventsSeen.register(event.EventID)
	if tag.RowsAffected() == 0 {
		// A concurrent duplicate delivery already committed this event's row.
		log.Printf("[SQUARE-WEBHOOK] Duplicate event_id %s; acknowledging (already processed)", event.EventID)
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
		return
	}

	w.WriteHeader(http.StatusOK)
	_, _ = w.Write([]byte("ok"))
}

func verifySquareSignature(body []byte, signature, signingKey, notificationURL string) bool {
	mac := hmac.New(sha256.New, []byte(signingKey))
	mac.Write([]byte(notificationURL))
	mac.Write(body)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(signature), []byte(expected))
}

// squareWebhookData is the `data` envelope of a Square webhook v1 event. The
// affected object's id is at data.id; the full resource is nested at
// data.object.<type> (e.g. data.object.payment). Only the id is logged — the
// nested object can contain PII and is never echoed to the log.
type squareWebhookData struct {
	ID     string          `json:"id"`
	Type   string          `json:"type"`
	Object json.RawMessage `json:"object"`
}

// squareDisputePayload maps the Square Dispute fields this app records.
// Reference: https://developer.squareup.com/reference/square/objects/Dispute
type squareDisputePayload struct {
	ID              string                      `json:"id"`
	State           string                      `json:"state"`
	AmountMoney     *squareMoneyPayload         `json:"amount_money"`
	Reason          string                      `json:"reason"`
	DisputedPayment *squareDisputedPaymentField `json:"disputed_payment"`
}

type squareMoneyPayload struct {
	Amount   int64  `json:"amount"` // minor units (pence for GBP)
	Currency string `json:"currency"`
}

type squareDisputedPaymentField struct {
	PaymentID string `json:"payment_id"`
}

// squarePaymentPayload maps the Square Payment fields this app consumes.
type squarePaymentPayload struct {
	ID     string `json:"id"`
	Status string `json:"status"` // "APPROVED", "COMPLETED", "CANCELED", "FAILED", "PENDING"
}

// squareRefundPayload maps the Square Refund (PaymentRefund) fields this app
// consumes.
type squareRefundPayload struct {
	ID     string `json:"id"`
	Status string `json:"status"` // "PENDING", "COMPLETED", "FAILED"
}

// parseSquareObject unmarshals data.object.<type> into out. Returns false when
// the nested resource is absent (legacy envelope carrying only data.id).
func parseSquareObject(object json.RawMessage, key string, out any) bool {
	if len(object) == 0 {
		return false
	}
	var wrapper map[string]json.RawMessage
	if err := json.Unmarshal(object, &wrapper); err != nil {
		return false
	}
	raw, ok := wrapper[key]
	if !ok || len(raw) == 0 {
		return false
	}
	if err := json.Unmarshal(raw, out); err != nil {
		return false
	}
	return true
}

// squareMoneyToAmount converts a Square Money object (minor units) to an exact
// two-decimal string for the NUMERIC(10,2) columns. String formatting avoids
// float64 rounding artifacts for money.
func squareMoneyToAmount(m *squareMoneyPayload) string {
	if m == nil || m.Amount <= 0 {
		return "0.00"
	}
	return fmt.Sprintf("%d.%02d", m.Amount/100, m.Amount%100)
}

// squarePaymentStatusToLocal maps Square's payment state machine to the local
// payment_status enum. APPROVED/PENDING are NON-terminal (Square may still
// complete or void them), so they map to a zero local status and the caller
// leaves the row untouched — the same classification the stale-pending sweeps
// use (handlers/payments/sweep.go).
func squarePaymentStatusToLocal(status string) (string, bool) {
	switch status {
	case "COMPLETED":
		return "completed", true
	case "CANCELED", "FAILED":
		return "failed", true
	case "APPROVED", "PENDING":
		return "", false
	default:
		return "", false
	}
}

// squareRefundStatusToLocal maps Square's refund status to the local
// payment_status enum. PENDING is non-terminal.
func squareRefundStatusToLocal(status string) (string, bool) {
	switch status {
	case "COMPLETED":
		return "completed", true
	case "FAILED":
		return "failed", true
	default:
		return "", false
	}
}

// squareDisputeStateToLocal maps Square's dispute state to the local
// disputes.status. Only the terminal resolutions move the row to won/lost;
// ACCEPTED (seller accepted the dispute) is a loss — the money is gone.
// Everything else (inquiries, evidence required, processing) stays open.
func squareDisputeStateToLocal(state string) string {
	switch state {
	case "WON":
		return "won"
	case "LOST", "ACCEPTED":
		return "lost"
	default:
		return "open"
	}
}

// findPaymentBySquareID resolves the local payment id and booking id for a
// Square payment id. Multiple local rows can share one Square charge id (e.g.
// a deposit + balance split); the most recent is used.
func findPaymentBySquareID(squarePaymentID string) (paymentID, bookingID string, ok bool) {
	if squarePaymentID == "" {
		return "", "", false
	}
	var pid string
	var bid *string
	err := db.Conn.QueryRow(context.Background(), `
		SELECT id, booking_id FROM payments
		WHERE square_payment_id = $1
		ORDER BY created_at DESC, id DESC
		LIMIT 1
	`, squarePaymentID).Scan(&pid, &bid)
	if err != nil {
		return "", "", false
	}
	if bid != nil {
		bookingID = *bid
	}
	return pid, bookingID, true
}

// findPaymentByDisputeID resolves the local payment (and its booking) recorded
// for a dispute row. Used by dispute.state.updated when the dispute row already
// exists but the webhook payload carries no resolvable Square payment id.
func findPaymentByDisputeID(squareDisputeID string) (paymentID, bookingID string) {
	var pid string
	var bid *string
	err := db.Conn.QueryRow(context.Background(), `
		SELECT d.payment_id, p.booking_id
		FROM disputes d
		JOIN payments p ON p.id = d.payment_id
		WHERE d.square_dispute_id = $1
	`, squareDisputeID).Scan(&pid, &bid)
	if err != nil {
		return "", ""
	}
	if bid != nil {
		bookingID = *bid
	}
	return pid, bookingID
}

// disputeNotificationID derives the deterministic admin_notifications id for an
// untracked dispute's critical_payment_log notification: 'D' + 11 lowercase hex
// chars of a SHA-256 over 'dispute-<square_dispute_id>'. generate_short_id
// (init-script.sql) only ever emits 12 lowercase hex chars
// (substr(encode(gen_random_bytes(6),'hex'),1,12)), so the uppercase 'D' prefix
// guarantees this can never collide with a DB-generated id. The id is stable
// per dispute, giving ON CONFLICT (id) DO NOTHING per-dispute idempotency.
func disputeNotificationID(squareDisputeID string) string {
	sum := sha256.Sum256([]byte("dispute-" + squareDisputeID))
	return "D" + hex.EncodeToString(sum[:])[:11]
}

// insertCriticalPaymentNotification surfaces a money event in the admin
// notification centre (reason='critical_payment_log'), the DB-backed stand-in
// for un-watched CRITICAL log lines (see ScanCriticalPaymentLogs in
// internal/jobs/cleanup.go). Dedup: one unacknowledged row per (reason,
// booking_id) — acknowledging re-arms it.
//
// Untracked disputes (no local payment row, booking_id NULL) pass disputeID
// instead: each DISTINCT square dispute gets its OWN notification under the
// deterministic id (disputeNotificationID), so a second distinct chargeback is
// never suppressed by the first's (reason, NULL booking) row — and re-delivery
// of the same dispute is a no-op (ON CONFLICT (id) DO NOTHING). The
// booking-scoped NOT EXISTS guard does NOT apply to this path: it would
// collapse every untracked dispute onto one unacknowledged NULL-booking row.
func insertCriticalPaymentNotification(bookingID, disputeID string) {
	if disputeID != "" {
		id := disputeNotificationID(disputeID)
		tag, err := db.Conn.Exec(context.Background(), `
			INSERT INTO admin_notifications (id, reason, booking_id, created_at)
			VALUES ($1, 'critical_payment_log'::admin_notification_reason, NULL, NOW())
			ON CONFLICT (id) DO NOTHING
		`, id)
		if err != nil {
			log.Printf("[SQUARE-WEBHOOK] Failed to insert critical_payment_log admin notification: %v", err)
			return
		}
		if tag.RowsAffected() > 0 {
			log.Printf("[SQUARE-WEBHOOK] Inserted critical_payment_log admin notification (dispute_id=%s, booking_id=NULL)", disputeID)
		}
		return
	}
	var bid any
	if bookingID != "" {
		bid = bookingID
	}
	tag, err := db.Conn.Exec(context.Background(), `
		INSERT INTO admin_notifications (reason, booking_id, created_at)
		SELECT 'critical_payment_log'::admin_notification_reason, $1, NOW()
		WHERE NOT EXISTS (
			SELECT 1 FROM admin_notifications an
			WHERE an.reason = 'critical_payment_log'
			  AND an.booking_id IS NOT DISTINCT FROM $1
			  AND an.acknowledged_at IS NULL
		)
	`, bid)
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to insert critical_payment_log admin notification: %v", err)
		return
	}
	if tag.RowsAffected() > 0 {
		log.Printf("[SQUARE-WEBHOOK] Inserted critical_payment_log admin notification (booking_id=%s)", bookingID)
	}
}

// markPaymentFailed flips a payment to 'failed' after a lost dispute — the
// money was charged back, so the row must not read as collected. 'refunded'
// rows are left alone (the money was returned by refund, not charged back).
func markPaymentFailed(paymentID string) error {
	if paymentID == "" {
		return nil
	}
	_, err := db.Conn.Exec(context.Background(),
		"UPDATE payments SET status = 'failed', updated_at = NOW() WHERE id = $1 AND status IN ('pending', 'completed')",
		paymentID)
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to mark payment %s failed after lost dispute: %v", paymentID, err)
		return err
	}
	return nil
}

// handlePaymentUpdated reconciles a Square Payment state change against the
// local payments row (real-time counterpart to the stale-pending sweep). The
// Square id is logged, never the payload (PII). Idempotent: the UPDATE is a
// no-op when the local status already matches, and event_id dedup prevents
// re-entry at the handler level. A non-nil error means dispatch failed and the
// caller must NOT commit the dedup row (Square retries).
func handlePaymentUpdated(ctx context.Context, data json.RawMessage) error {
	var env squareWebhookData
	if err := json.Unmarshal(data, &env); err != nil {
		log.Printf("[SQUARE-WEBHOOK] payment.updated received (payload length=%d)", len(data))
		return nil
	}
	if env.ID == "" {
		log.Printf("[SQUARE-WEBHOOK] payment.updated received (payload length=%d)", len(data))
		return nil
	}
	var payment squarePaymentPayload
	if !parseSquareObject(env.Object, "payment", &payment) || payment.ID == "" || payment.Status == "" {
		log.Printf("[SQUARE-WEBHOOK] payment.updated received (data.id=%s)", env.ID)
		return nil
	}
	localStatus, terminal := squarePaymentStatusToLocal(payment.Status)
	if !terminal {
		log.Printf("[SQUARE-WEBHOOK] payment.updated: square payment %s status %q is non-terminal — no local state change", payment.ID, payment.Status)
		return nil
	}
	// Only 'pending' rows are candidates for a terminal transition — the same
	// conservative rule the stale-pending sweeps use. A webhook for an already
	// settled row (Square fires payment.updated for ANY field change, e.g. fee
	// recalculation on a fully-refunded charge) must never revert a terminal
	// status like 'refunded' back to 'completed'.
	tag, err := db.Conn.Exec(context.Background(),
		`UPDATE payments SET status = $1, updated_at = NOW() WHERE square_payment_id = $2 AND status = 'pending'`,
		localStatus, payment.ID)
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to update payment %s to status %s: %v", payment.ID, localStatus, err)
		return err
	}
	if tag.RowsAffected() > 0 {
		log.Printf("[SQUARE-WEBHOOK] payment.updated: square payment %s → local status %s", payment.ID, localStatus)
	}
	// A Square charge can also map to a till_sales row (online gift-card
	// purchase, retail at the till) — reconcile those too. Same pending-only
	// guard: never revert a terminal till-sale status. A definitively failed
	// charge (Square FAILED/CANCELED) claws back the gift-card funding those
	// pending sales added, exactly like the stale-pending sweep
	// (handlers/payments/sweep.go); an ambiguous status never reaches here.
	if localStatus == "failed" {
		return clawbackFailedTillSales(ctx, payment.ID)
	}
	tsTag, err := db.Conn.Exec(context.Background(),
		`UPDATE till_sales SET status = $1, updated_at = NOW() WHERE square_payment_id = $2 AND status = 'pending'`,
		localStatus, payment.ID)
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to reconcile till_sales for square payment %s: %v", payment.ID, err)
		return err
	}
	if tsTag.RowsAffected() > 0 {
		log.Printf("[SQUARE-WEBHOOK] payment.updated: reconciled %d till_sale(s) for square payment %s → status %s", tsTag.RowsAffected(), payment.ID, localStatus)
	}
	return nil
}

// clawbackFailedTillSales reverts the gift-card funding of every still-pending
// till sale funded by a Square charge that is DEFINITIVELY failed (Square
// FAILED/CANCELED — never ambiguous). It mirrors the stale-pending sweep's
// clawbackTillSaleFunding + revertGiftCardFunding (handlers/payments/sweep.go,
// till.go): each sale is claimed with a status='pending' guard so an
// already-resolved row is skipped without error, and the failed mark + funding
// revert commit atomically. A non-nil error means a DB failure left a pending
// sale's funding unreverted — the caller rejects the webhook so Square retries
// the clawback (the sweep is the eventual backstop).
func clawbackFailedTillSales(ctx context.Context, squarePaymentID string) error {
	rows, err := db.Conn.Query(context.Background(), `
		SELECT ts.id, ts.item_type, ts.item_id, ts.total_amount, gc.redeemed_by,
		       (ts.created_at = gc.created_at) AS is_create
		FROM till_sales ts
		LEFT JOIN gift_cards gc ON gc.id = ts.item_id
		WHERE ts.square_payment_id = $1 AND ts.status = 'pending'
	`, squarePaymentID)
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to read pending till_sales for funding clawback (square payment %s): %v", squarePaymentID, err)
		return err
	}
	defer rows.Close()
	for rows.Next() {
		var (
			saleID      string
			itemType    string
			itemID      sql.NullString
			totalAmount float64
			redeemedBy  sql.NullString
			isCreate    *bool
		)
		if err := rows.Scan(&saleID, &itemType, &itemID, &totalAmount, &redeemedBy, &isCreate); err != nil {
			log.Printf("[SQUARE-WEBHOOK] Failed to scan pending till_sale for funding clawback (square payment %s): %v", squarePaymentID, err)
			return err
		}
		if err := clawbackOneTillSale(ctx, saleID, itemType, itemID, totalAmount, redeemedBy, isCreate); err != nil {
			return err
		}
	}
	return rows.Err()
}

// clawbackOneTillSale resolves one pending till sale of a definitively failed
// charge. A gift-card sale has its funding reverted atomically with the failed
// mark; a sale with no gift card (future retail product / orphaned item) is
// only marked failed. An already-resolved sale is skipped, not an error.
func clawbackOneTillSale(ctx context.Context, saleID, itemType string, itemID sql.NullString, totalAmount float64, redeemedBy sql.NullString, isCreate *bool) error {
	if itemType != "gift_card" || !itemID.Valid || itemID.String == "" || isCreate == nil {
		// No gift card to claw back — mark the sale failed without touching
		// any card (mirrors the sweep's non-gift-card branch).
		tag, err := db.Conn.Exec(context.Background(), `
			UPDATE till_sales SET status = 'failed', updated_at = NOW()
			WHERE id = $1 AND status = 'pending'
		`, saleID)
		if err != nil {
			log.Printf("[SQUARE-WEBHOOK] Failed to mark till sale %s failed: %v", saleID, err)
			return err
		}
		if tag.RowsAffected() > 0 {
			log.Printf("[SQUARE-WEBHOOK] payment.updated: marked till sale %s failed (no gift card to claw back)", saleID)
		}
		return nil
	}
	action := "topup"
	if *isCreate {
		action = "create"
	}
	var redeem *string
	if redeemedBy.Valid && redeemedBy.String != "" {
		redeem = &redeemedBy.String
	}
	if err := revertTillSaleGiftCardFunding(ctx, action, itemID.String, totalAmount, redeem, saleID); err != nil {
		if payments.IsTillSaleNotPending(err) {
			log.Printf("[SQUARE-WEBHOOK] Till sale %s was already resolved (not pending) — skipping funding clawback", saleID)
			return nil
		}
		log.Printf("CRITICAL: [SQUARE-WEBHOOK] failed to claw back gift card %s funding for failed till sale %s: %v — MANUAL RECONCILIATION REQUIRED: gift card may still be funded", itemID.String, saleID, err)
		return err
	}
	return nil
}

// revertTillSaleGiftCardFunding undoes the gift-card funding of a till sale
// whose charge definitively failed. It delegates to the single shared clawback
// implementation, payments.RevertGiftCardFunding (handlers/payments/
// giftcard_clawback.go) — the same helper the till handler and the stale-pending
// sweep use — so the webhook's money reversal can never drift from theirs. The
// claim-first status='pending' guard, the create/top-up branches, the
// redeem-to-user reversal, the CRITICAL reconciliation log lines and the
// errTillSaleNotPending sentinel all live in that one place.
func revertTillSaleGiftCardFunding(ctx context.Context, action, giftCardID string, amount float64, redeemToUserID *string, tillSaleID string) error {
	return payments.RevertGiftCardFunding(ctx, action, giftCardID, amount, redeemToUserID, tillSaleID)
}

// handleRefundUpdated reconciles a Square Refund state change against the local
// refunds row. Idempotent (status-guarded UPDATE + event_id dedup). A non-nil
// error means dispatch failed and the caller must NOT commit the dedup row.
func handleRefundUpdated(data json.RawMessage) error {
	var env squareWebhookData
	if err := json.Unmarshal(data, &env); err != nil {
		log.Printf("[SQUARE-WEBHOOK] refund.updated received (payload length=%d)", len(data))
		return nil
	}
	if env.ID == "" {
		log.Printf("[SQUARE-WEBHOOK] refund.updated received (payload length=%d)", len(data))
		return nil
	}
	var refund squareRefundPayload
	if !parseSquareObject(env.Object, "refund", &refund) || refund.ID == "" || refund.Status == "" {
		log.Printf("[SQUARE-WEBHOOK] refund.updated received (data.id=%s)", env.ID)
		return nil
	}
	localStatus, terminal := squareRefundStatusToLocal(refund.Status)
	if !terminal {
		log.Printf("[SQUARE-WEBHOOK] refund.updated: square refund %s status %q is non-terminal — no local state change", refund.ID, refund.Status)
		return nil
	}
	// COMPLETED may promote any non-completed row (incl. a sweep-failed refund
	// Square later shows complete) — the over-refund guard counts completed
	// refunds, so this only tightens it. FAILED only demotes a 'pending' row:
	// demoting 'completed' would let the guard exclude money that already moved
	// (the exact risk refunds.go documents for failed refunds).
	var upd string
	switch localStatus {
	case "completed":
		upd = `UPDATE refunds SET status = 'completed' WHERE square_refund_id = $1 AND status <> 'completed'`
	case "failed":
		upd = `UPDATE refunds SET status = 'failed' WHERE square_refund_id = $1 AND status = 'pending'`
	}
	tag, err := db.Conn.Exec(context.Background(), upd, refund.ID)
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to update refund %s to status %s: %v", refund.ID, localStatus, err)
		return err
	}
	if tag.RowsAffected() > 0 {
		log.Printf("[SQUARE-WEBHOOK] refund.updated: square refund %s → local status %s", refund.ID, localStatus)
	}
	return nil
}

// truncateDisputeReason caps a Square dispute reason at the disputes.reason
// VARCHAR(192) column width. An over-long reason would fail the disputes
// INSERT; the handler treats that as a dispatch error (no dedup row, 5xx), so
// Square would retry forever — truncating lets the event succeed instead.
// VARCHAR(192) counts CHARACTERS, not bytes, so truncation must slice on a rune
// boundary: byte-slicing (reason[:192]) can split a multi-byte UTF-8 rune and
// store invalid UTF-8 (which Postgres rejects), failing the INSERT the same way
// an over-long reason would. Slicing the []rune form keeps the stored reason a
// valid, at-most-192-character UTF-8 string.
func truncateDisputeReason(reason string) string {
	runes := []rune(reason)
	if len(runes) > 192 {
		return string(runes[:192])
	}
	return reason
}

// handleDisputeCreated records a newly opened dispute: inserts the disputes row
// and surfaces a critical_payment_log admin notification so the owner sees the
// chargeback in-app. A disputed Square payment with NO local payments row (a
// Dashboard-initiated charge, a mismatched Square id, or a deleted/erased row)
// cannot be reconciled to a booking — no disputes row is written — but the
// admin notification is STILL raised with booking_id NULL, because there is no
// sweep fallback for disputes and a chargeback the app cannot see is a silent
// money-loss path the owner must always be told about. Idempotent via
// ON CONFLICT (square_dispute_id) DO NOTHING plus the event_id dedup. A non-nil
// error means dispatch failed (no dedup row committed — Square retries).
func handleDisputeCreated(data json.RawMessage) error {
	var env squareWebhookData
	if err := json.Unmarshal(data, &env); err != nil {
		log.Printf("[SQUARE-WEBHOOK] dispute.created received (payload length=%d)", len(data))
		return nil
	}
	var dispute squareDisputePayload
	if !parseSquareObject(env.Object, "dispute", &dispute) || dispute.ID == "" {
		log.Printf("[SQUARE-WEBHOOK] dispute.created received (data.id=%s)", env.ID)
		return nil
	}
	squarePaymentID := ""
	if dispute.DisputedPayment != nil {
		squarePaymentID = dispute.DisputedPayment.PaymentID
	}
	paymentID, bookingID, paymentFound := findPaymentBySquareID(squarePaymentID)
	if !paymentFound {
		// Untracked chargeback: no local payments row for this Square charge
		// (Dashboard-initiated, mismatched Square payment id, or a deleted/erased
		// row). There is NO sweep fallback for disputes — this notification is
		// the only in-app trace the owner gets that Square is clawing back funds,
		// so it must never be skipped. booking_id stays NULL; each DISTINCT
		// dispute gets its OWN deterministic-id notification (the booking-scoped
		// dedup would collapse separate chargebacks into one suppressed row).
		// Still return nil so the dedup row commits and Square's retry is
		// acknowledged.
		log.Printf("[SQUARE-WEBHOOK] CRITICAL: dispute %s created for square payment %q with NO local payment row — chargeback cannot be reconciled in-app — admin notified (booking_id NULL)", dispute.ID, squarePaymentID)
		insertCriticalPaymentNotification("", dispute.ID)
		return nil
	}
	amount := squareMoneyToAmount(dispute.AmountMoney)
	tag, err := db.Conn.Exec(context.Background(), `
		INSERT INTO disputes (square_dispute_id, payment_id, status, amount, reason, created_at, updated_at)
		VALUES ($1, $2, 'open', $3, NULLIF($4, ''), NOW(), NOW())
		ON CONFLICT (square_dispute_id) DO NOTHING
	`, dispute.ID, paymentID, amount, truncateDisputeReason(dispute.Reason))
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to insert dispute %s: %v", dispute.ID, err)
		return err
	}
	_ = tag
	insertCriticalPaymentNotification(bookingID, "")
	log.Printf("[SQUARE-WEBHOOK] CRITICAL: dispute %s created (amount %s, reason %q) for square payment %s — admin notified", dispute.ID, amount, dispute.Reason, squarePaymentID)
	return nil
}

// handleDisputeStateUpdated applies a Square dispute state change to the local
// disputes row (upsert — a state.updated may arrive before the created event),
// and on a terminal loss marks the payment failed + raises CRITICAL. Won is
// logged only. Idempotent: the upsert converges to the same row. A non-nil
// error means dispatch failed (no dedup row committed — Square retries).
func handleDisputeStateUpdated(data json.RawMessage) error {
	var env squareWebhookData
	if err := json.Unmarshal(data, &env); err != nil {
		log.Printf("[SQUARE-WEBHOOK] dispute.state.updated received (payload length=%d)", len(data))
		return nil
	}
	var dispute squareDisputePayload
	if !parseSquareObject(env.Object, "dispute", &dispute) || dispute.ID == "" {
		log.Printf("[SQUARE-WEBHOOK] dispute.state.updated received (data.id=%s)", env.ID)
		return nil
	}
	localStatus := squareDisputeStateToLocal(dispute.State)
	amount := squareMoneyToAmount(dispute.AmountMoney)

	squarePaymentID := ""
	if dispute.DisputedPayment != nil {
		squarePaymentID = dispute.DisputedPayment.PaymentID
	}
	paymentID, bookingID, paymentFound := findPaymentBySquareID(squarePaymentID)
	if !paymentFound {
		// Row may already exist from dispute.created — recover its payment.
		paymentID, bookingID = findPaymentByDisputeID(dispute.ID)
		if paymentID == "" {
			log.Printf("[SQUARE-WEBHOOK] dispute.state.updated: no local payment for dispute %s (square payment %q) — cannot record state %s", dispute.ID, squarePaymentID, dispute.State)
			return nil
		}
	}

	_, err := db.Conn.Exec(context.Background(), `
		INSERT INTO disputes (square_dispute_id, payment_id, status, amount, reason, created_at, updated_at)
		VALUES ($1, $2, $3, $4, NULLIF($5, ''), NOW(), NOW())
		ON CONFLICT (square_dispute_id) DO UPDATE
		SET status = EXCLUDED.status, amount = EXCLUDED.amount,
		    reason = EXCLUDED.reason, updated_at = NOW()
	`, dispute.ID, paymentID, localStatus, amount, truncateDisputeReason(dispute.Reason))
	if err != nil {
		log.Printf("[SQUARE-WEBHOOK] Failed to update dispute %s to state %s: %v", dispute.ID, dispute.State, err)
		return err
	}

	switch localStatus {
	case "lost":
		if err := markPaymentFailed(paymentID); err != nil {
			return err
		}
		insertCriticalPaymentNotification(bookingID, "")
		log.Printf("[SQUARE-WEBHOOK] CRITICAL: dispute %s LOST — payment %s marked failed; admin notified", dispute.ID, paymentID)
	case "won":
		log.Printf("[SQUARE-WEBHOOK] dispute %s WON — resolved in seller's favour; no action", dispute.ID)
	default:
		log.Printf("[SQUARE-WEBHOOK] dispute %s state → %s (status %s)", dispute.ID, dispute.State, localStatus)
	}
	return nil
}

// handleDisputeEvidence logs evidence submissions/removals. Evidence does not
// change the dispute's local status, so it is informational only.
func handleDisputeEvidence(data json.RawMessage) error {
	var env squareWebhookData
	if err := json.Unmarshal(data, &env); err != nil {
		log.Printf("[SQUARE-WEBHOOK] dispute evidence event received (payload length=%d)", len(data))
		return nil
	}
	var dispute squareDisputePayload
	if !parseSquareObject(env.Object, "dispute", &dispute) || dispute.ID == "" {
		log.Printf("[SQUARE-WEBHOOK] dispute evidence event received (data.id=%s)", env.ID)
		return nil
	}
	log.Printf("[SQUARE-WEBHOOK] dispute evidence event for dispute %s (state %s)", dispute.ID, dispute.State)
	return nil
}

// handleTerminalCheckout logs terminal checkout lifecycle events. Terminal
// checkout state is owned by the poll/sweep handlers (handlers/payments/),
// which fetch the authoritative status from Square — no state mutation here.
func handleTerminalCheckout(data json.RawMessage) error {
	var env squareWebhookData
	if err := json.Unmarshal(data, &env); err != nil {
		log.Printf("[SQUARE-WEBHOOK] terminal.checkout event received (payload length=%d)", len(data))
		return nil
	}
	log.Printf("[SQUARE-WEBHOOK] terminal.checkout event received (data.id=%s)", env.ID)
	return nil
}