JavaScript Events

The plugin's front-end emits DOM CustomEvents for every major bidding interaction. Listen and react to integrate with your own scripts.

Conventions

  • All events dispatch on document (bubble up — listen wherever)
  • Event prefix: wkafw:*
  • All payloads in event.detail

Event reference

Bid lifecycle

document.addEventListener('wkafw:bid_placed', (e) => {
  console.log('Bid:', e.detail);
  // { auctionId, bidId, amount, userId, placedAt }
});

document.addEventListener('wkafw:bid_failed', (e) => {
  console.log('Failed:', e.detail);
  // { auctionId, error: 'wkafw_bid_below_increment', message }
});

document.addEventListener('wkafw:outbid', (e) => {
  // user was outbid
  // { auctionId, newHighAmount, newHighBidder }
});

Auction state changes

document.addEventListener('wkafw:auction_started', (e) => {
  // scheduled → active
});

document.addEventListener('wkafw:auction_ended', (e) => {
  // ended (closed)
});

document.addEventListener('wkafw:auction_extended', (e) => {
  // anti-snipe extension fired
  // { auctionId, newEndDate, extensionSeconds }
});

Watchlist

document.addEventListener('wkafw:watch_added', (e) => {
  // { auctionId, userId }
});

document.addEventListener('wkafw:watch_removed', (e) => {
  // { auctionId, userId }
});

Polling

document.addEventListener('wkafw:poll_tick', (e) => {
  // every poll cycle
  // { auctionId, currentPrice, bidCount, secondsLeft, watchersCount }
});

document.addEventListener('wkafw:poll_started', (e) => {
  // polling activated
});

document.addEventListener('wkafw:poll_stopped', (e) => {
  // polling stopped (auction ended or dormant)
});

Wallet

document.addEventListener('wkafw:wallet_balance_changed', (e) => {
  // { newBalance, delta, reference }
});

UI

document.addEventListener('wkafw:countdown_color_change', (e) => {
  // { auctionId, oldColor, newColor }
});

document.addEventListener('wkafw:confetti', (e) => {
  // confetti burst started
});

Programmatic dispatch

The plugin exposes a global window.wkafw for programmatic interaction:

// Place a bid programmatically
window.wkafw.placeBid({
  auctionId: 123,
  amount: 5550.00,
  onSuccess: (bid) => console.log('Bid:', bid),
  onError: (err) => console.error('Error:', err),
});

// Toggle watchlist
window.wkafw.toggleWatch(123);

// Get current auction state
const state = window.wkafw.getAuctionState(123);
// { currentPrice, bidCount, secondsLeft, ... }

// Force a poll refresh
window.wkafw.refreshAuction(123);

// Get user's wallet balance
window.wkafw.getWalletBalance().then(balance => {
  console.log(balance);
});

Custom integrations

Show a custom toast on outbid

document.addEventListener('wkafw:outbid', (e) => {
  myCustomToast({
    title: 'Outbid!',
    body: `New high: $${e.detail.newHighAmount}`,
    action: { label: 'Bid again', url: `#auction-${e.detail.auctionId}` },
  });
});

Audio cues

const bidSound = new Audio('/path/to/bid.mp3');
const winSound = new Audio('/path/to/win.mp3');

document.addEventListener('wkafw:bid_placed', () => bidSound.play());
document.addEventListener('wkafw:auction_ended', (e) => {
  if (e.detail.youWon) winSound.play();
});

React-style integration

function useAuction(auctionId) {
  const [state, setState] = useState(window.wkafw.getAuctionState(auctionId));

  useEffect(() => {
    const handler = (e) => {
      if (e.detail.auctionId === auctionId) {
        setState(prev => ({ ...prev, ...e.detail }));
      }
    };
    document.addEventListener('wkafw:poll_tick', handler);
    return () => document.removeEventListener('wkafw:poll_tick', handler);
  }, [auctionId]);

  return state;
}

Server-sent events (SSE)

For very-low-latency real-time updates (instead of polling), the plugin can fall back to SSE if your server supports it:

const sse = new EventSource('/wp-json/wkafw/v1/stream/auction/123');
sse.addEventListener('bid_placed', (e) => {
  const bid = JSON.parse(e.data);
  console.log('SSE bid:', bid);
});

SSE auto-disabled by default (most shared hosting blocks it). Enable via:

update_option( 'wkafw_sse_enabled', 'yes' );

Polling configuration

The polling interval is controlled by:

window.wkafw.config = {
  pollIntervalNormal: 30,    // seconds
  pollIntervalEndgame: 3,    // seconds (last 2 minutes)
  endgameThreshold: 120,     // seconds (when to switch to fast polling)
  dormantThreshold: 1800,    // seconds (no bids = stop polling)
};

Override programmatically (before any auction page renders):

window.wkafwSettings = window.wkafwSettings || {};
window.wkafwSettings.pollIntervalNormal = 60; // slower polling

Debugging

Enable verbose logging:

localStorage.setItem('wkafw:debug', '1');

Then watch the browser console for every event, poll, and AJAX request.