SeuraaEdge
Docs/Use Cases
Use Cases

Push private realtime updates to individual users.

Build Notifications

Use notifications when your backend needs to push a private update to a user without waiting for the next page load or poll.

Common examples include completed exports, approvals, mentions, failed payments, status changes, match invites, and live game stats.

Model The Channel

Use one private channel per recipient:

ts
const channelName = `private:user:${user.id}:notifications`;

Only that user should receive a signed channel token for this channel. Your backend signs the token locally with appSecret; Edge verifies it when the client subscribes. Keep notification publishing on your backend so the browser cannot forge authoritative events.

Sign A Token

Create an authenticated token endpoint in your app:

ts
import { Client } from "@seuraa/edge-node";

const edge = new Client({
  appKey: process.env.SEURAA_APP_KEY!,
  appSecret: process.env.SEURAA_APP_SECRET!,
});

export async function POST(request: Request) {
  const user = await requireUser(request);
  const { channel } = await request.json();

  if (channel !== `private:user:${user.id}:notifications`) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  }

  const session = edge.auth.signIn({
    channel,
    expiresInSeconds: 60,
    permissions: ["subscribe"],
    userId: user.id,
  });

  return Response.json({ token: session.token });
}

edge.auth.signIn(...) does not make a network request to Edge. It creates a short-lived channel token in your trusted backend code.

Subscribe In The Client

Subscribe after the user signs in:

ts
import { Client } from "@seuraa/edge";

const edge = new Client({
  appKey: "app-key",
  auth: "/api/edge/token",
});

const channel = edge.channel(`private:user:${currentUser.id}:notifications`);

channel.subscribe<{
  reportId: string;
  title: string;
  body?: string;
  url?: string;
}>("report.ready", (event) => {
  showToast({
    title: event.data.title,
    body: event.data.body,
    url: event.data.url,
  });
});

Clean Up The Subscription

When the notification surface is no longer active, leave the channel:

ts
channel.unsubscribe();

Publish From Your Backend

Publish when the application event happens:

ts
await edge.channels.publish(
  `private:user:${userId}:notifications`,
  "report.ready",
  {
    reportId: report.id,
    title: "Your export is ready",
    body: "Download the CSV from your reports page.",
    url: `/reports/${report.id}`,
  },
  { clientEventId: report.id },
);

Use a stable clientEventId when retrying the same notification so clients can ignore duplicates.

What To Store

Edge delivers the live event. Your application should still store durable notification records when users need an inbox, read state, email fallback, or history across devices.

Use Edge for the realtime path and your database for the product record.

Generate This With AI

Use this prompt to generate a complete TanStack Start app that demonstrates the flow end to end.

text
Build a complete TanStack Start app that demonstrates realtime notifications with Seuraa Edge.

Use @seuraa/edge in the browser and @seuraa/edge-node only in trusted backend code.

Implement:
- A minimal UI with a signed-in demo user, a notification tray, and toast-style notifications.
- A TanStack Start API route at /api/edge/token.
- The endpoint must use a small mock requireUser() helper, accept { channel }, and only allow channel === `private:user:${user.id}:notifications`.
- The endpoint must sign a short-lived channel token locally with edge.auth.signIn({ channel, expiresInSeconds: 60, permissions: ["subscribe"], userId: user.id }).
- Do not call Edge to mint channel tokens. The backend SDK signs locally with SEURAA_APP_SECRET.
- A browser notification component that creates edge.channel(`private:user:${currentUser.id}:notifications`).
- Subscribe to the product event "report.ready".
- Show a toast from { reportId, title, body, url }.
- Call channel.unsubscribe() when the notification surface unmounts or the user signs out.
- A TanStack Start API route at /api/reports/demo-ready that publishes "report.ready" to `private:user:${userId}:notifications` with a stable clientEventId.
- A button in the UI that calls /api/reports/demo-ready so the realtime notification can be tested.
- Loading, connected, and error states in the UI.
- A .env.example file and short README instructions for running the app.

Use these environment variables:
- SEURAA_APP_KEY
- SEURAA_APP_SECRET

Do not expose SEURAA_APP_SECRET to browser code.