realtime: Supabase Realtime for KDS + order tracking

[snackman]

@

Summary

Upgrades the realtime layer from interval polling to Supabase Realtime, behind the existing getRealtimeProvider() seam. The KDS board and the customer order tracker now receive instant websocket pushes in production, with zero component changes and the zero-env build/preview/test invariant fully intact.

• src/lib/realtime/supabase.ts — replaces the documented stub with a real createSupabaseRealtimeProvider(). Subscribes to postgres_changes (event: "*") on public.orders, scoped by a server-side filter parsed from the topic the hooks already pass: kds:<tenant>:<location> → location_id=eq.<location>, track:<orderId> → id=eq.<orderId>. Uses the @supabase/ssr browser client (getBrowserSupabase()), so the socket runs as the signed-in user and Realtime enforces the same RLS SELECT policies as PostgREST.
  • Initial load via the same fetcher the poller used; live deltas re-run it (debounced 150ms, concurrent runs de-duped) so the server-computed payload (KDS elapsed/age/station, tracker live delivery state) stays the single source of truth.
  • Reconnect: re-fetches on each SUBSCRIBED transition to reconcile anything missed offline.
  • Cleanup: idempotent unsubscribe — cancels the pending debounce, removes the channel, ignores late results.
  • Graceful fallback: delegates to the poller for any subscription it can't serve (no browser client on SSR/RSC, or an unrecognised topic).
• src/lib/realtime/index.ts — getRealtimeProvider() selects Supabase Realtime when NEXT_PUBLIC_SUPABASE_URL + NEXT_PUBLIC_SUPABASE_ANON_KEY are present, else the poller. Read lazily at call time (memoized); nothing touches env at module load — mirrors the getPosDriver() / readDbConfig() guard.
• src/lib/realtime/realtime.test.ts — new env-free Vitest covering selection (poller with no env, Supabase with env, memoized) and the provider's per-subscription initial-fetch fallback for both topic shapes.
• supabase/README.md — new "Enabling Supabase Realtime" section with the exact publication SQL + verification queries.
• plans/focaccia-51842-realtime.md — design + plan.

Scope

Only the realtime layer + its doc/test. No new deps (@supabase/supabase-js and @supabase/ssr already present). No changes to auth/middleware, payments, next.config, or package.json. Components, money, and RLS correctness untouched.

Verified locally (no env vars)

npm install && npm run build && npm run typecheck && npm run lint && npm run test:run — all green (127 tests).

Orchestrator: enable Realtime on the LIVE DB

Run once on the live Supabase project (RLS is unchanged — Realtime reuses the existing orders SELECT policies):

-- Stream the full row on UPDATE/DELETE so the row filter matches the OLD row.
alter table public.orders replica identity full;

-- Add orders to the realtime publication (create it if the project lacks it).
do $$
begin
  if not exists (select 1 from pg_publication where pubname = 'supabase_realtime') then
    create publication supabase_realtime;
  end if;
end$$;

alter publication supabase_realtime add table public.orders;

Verify:

select schemaname, tablename from pg_publication_tables where pubname = 'supabase_realtime';
select relreplident from pg_class where oid = 'public.orders'::regclass;  -- expect 'f' (FULL)

Not required for the build/deploy — it only makes updates instant once env vars are set.

🤖 Generated with Claude Code
@

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pos	Ready	Preview, Comment	Jun 6, 2026 6:48am