Using QPub

Mental model

Account
  └── Project
        ├── API keys
        ├── Channels (pub/sub topics)
        └── Queues (durable jobs)
ConceptRole
AccountOrg/billing context in the dashboard
ProjectIsolation boundary for traffic and keys
API keypublicId:secret credential for REST and Socket
ChannelNamed topic string for pub/sub
QueueNamed durable job stream (REST)
AliasOptional client identity attached to a connection or message

Two client types

Socket (QPub.Socket)

Persistent WebSocket connection. Use for:

  • Subscribing to channels
  • Publishing from clients that already hold a connection
  • Connection lifecycle (reconnect, ping)

REST (QPub.Rest)

HTTP-only. Use for:

  • Publishing from servers and cron jobs
  • Batch publish to multiple channels
  • Issuing JWTs / creating token requests
  • Queue enqueue and workers

REST does not subscribe to channels.

Typical workflows

Real-time app

  1. Create a project and API key in the dashboard.
  2. On your server, keep the API key secret.
  3. For browsers, issue a JWT or signed token request with limited permissions.
  4. Client creates QPub.Socket, waits for connected, then channels.get(name).subscribe(...).
  5. Servers publish with QPub.Rest or another Socket client.

Server publish only

import { QPub } from "@qpub/sdk";

const rest = new QPub.Rest({ apiKey: process.env.QPUB_API_KEY });
await rest.channels.get("notifications").publish({ text: "Hello" });

Background jobs

const rest = new QPub.Rest({ apiKey: process.env.QPUB_API_KEY });
await rest.queues.enqueue("emails", { to: "[email protected]" });

// Blocks until stopWorker() is called
await rest.queues.runWorker("emails", async (job) => {
  // process job.payload
  return { ok: true };
});
// rest.queues.stopWorker();

Next steps

Edit this page on GitHub