feat(examples): managed session queue client reference

[AdirAmsalem]

Client reference for Decart's managed session queue: when an account's realtime concurrency is at its limit, users wait in a fair line with live position feedback. The queue manages the line only — it never mints, holds, or sees credentials. On granted, the app fetches a token from your own token endpoint (the standard realtime integration; see examples/express-proxy for the pattern) and connects within the claim window.

The whole client contract is three rules — poll every ~2s while waiting (stop polling or DELETE to leave), on granted fetch your token and connect within the claim window, and if a connect is ever refused, join again:

const { status, join, leave, sessionEnded, rejoin } = useQueue(fetchSession);
// status: idle | waiting {position, queueSize} | ready {session} | error
// fetchSession: your token endpoint → { apiKey } (mint with short expiresIn + maxSessionDuration)

The queue state machine lives in a framework-free QueueClient class (plain fetch + timers, no React dependencies — unit-testable and portable as-is) with a thin useSyncExternalStore hook binding; the camera/render component is the only platform-specific part. Same try-on UI and preloaded sample garment as the sibling realtime-session-queue example, which remains the self-hosted variant of the pattern for customers who want to own queueing themselves.

Verified end-to-end in a real browser against a live queue and a stand-in customer token endpoint: join → granted → own-token fetch → live session with output frames; with capacity saturated, a second tab waits with live position and inherits the slot when it frees.

---

Note

Low Risk
Documentation and example-only code; no production SDK or service changes.

Overview
Adds examples/realtime-session-queue-managed, a Vite/React reference app for Decart’s managed session queue (sibling to the self-hosted realtime-session-queue example).

The integration centers on a framework-free QueueClient that talks to /v1/queues/{id}/tickets with the publishable queue key, polls about every 2s while waiting, and on granted calls the app’s own fetchSession (your token endpoint — queue never mints credentials). A thin useQueue hook wires it with useSyncExternalStore; TryOnSession connects via @decartai/sdk and rejoins on refused connect.

The UI covers idle → waiting (position) → live try-on with a preloaded sample garment, plus README, .env.example, and pnpm-lock.yaml workspace entries.

^{Reviewed by Cursor Bugbot for commit 01bda8c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@decartai/sdk@190

commit: 3273961

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 01bda8c. Configure here.}

[cursor]

Stale position after poll grant

Low Severity

When grant arrives from pollLoop, claim runs without first setting waiting to position 1. The join-granted path does update to “you’re next” so a slow fetchSession does not look stuck; the poll path leaves the previous place-in-line UI until ready.

Additional Locations (1)

• examples/realtime-session-queue-managed/src/hooks/queue-client.ts#L92-L98

 

^{Reviewed by Cursor Bugbot for commit 01bda8c. Configure here.}