@socketly/server

Socketly from your backend: authorize subscriptions, and publish events.

npm install @socketly/server

Runs on Web Crypto and fetch, so the same build works in Node 18+, Bun, Deno, Vercel Edge Functions and Cloudflare Workers. Nothing here imports node:crypto.

Authorize a channel

private- and presence- channels need your server to say yes. You decide who may subscribe — you already know who your user is — and this signs that decision.

// app/api/socketly/auth/route.ts
import { authorizeChannel } from '@socketly/server';
import { getCurrentUser } from '@/lib/session';

export async function POST(request: Request) {
  const { socket_id, channel_name } = await request.json();

  const user = await getCurrentUser();
  if (!user) return new Response('Unauthorized', { status: 401 });

  if (channel_name.startsWith('private-room-')) {
    const roomId = channel_name.slice('private-room-'.length);
    if (!(await user.canAccessRoom(roomId))) {
      return new Response('Forbidden', { status: 403 });
    }
  }

  return Response.json(
    await authorizeChannel({
      secret: process.env.SOCKETLY_SECRET!, // sk_app_…
      socketId: socket_id,
      channel: channel_name,
    }),
  );
}

authorizeChannel is async — await it. There is no synchronous HMAC that works in every runtime; Web Crypto is promise-based, and the alternatives are locking this package to Node or hand-rolling SHA-256. The return type is a Promise, so TypeScript catches a missing await rather than letting you serialize {} into the response.

The signature is bound to that one socket id, so it cannot be replayed on another connection.

Presence

Presence channels also carry an identity, which is what the other members see:

await authorizeChannel({
  secret: process.env.SOCKETLY_SECRET!,
  socketId: socket_id,
  channel: channel_name,
  userData: {
    user_id: user.id,
    user_info: { name: user.name, avatar: user.avatarUrl },
  },
});

user_id is inside the signed payload, so a client cannot claim to be someone else. Return the result as-is: channel_data is the exact string that was signed, and re-serializing it would change the bytes and break the signature.

Publish

import { SocketlyServer } from '@socketly/server';

const socketly = new SocketlyServer({ secret: process.env.SOCKETLY_SECRET! });

await socketly.trigger('private-order-42', 'status', { state: 'shipped' });

Several channels at once, and skipping the socket that caused the change:

await socketly.trigger(
  ['private-order-42', 'private-user-7'],
  'status',
  { state: 'shipped' },
  { exceptSocketId: socketId }, // the originator already rendered it
);

trigger resolves to { delivered, remaining: { minute, day } }.

Who is in a presence channel

const { members, memberCount } = await socketly.channel('presence-room-42');

Errors

Any non-2xx throws a SocketlyError with status, code and the gateway's own message:

import { SocketlyError } from '@socketly/server';

try {
  await socketly.trigger('private-x', 'event', {});
} catch (err) {
  if (err instanceof SocketlyError && err.code === 'quota_exceeded') {
    // back off — err.status is 429
  }
  throw err;
}

Keep the secret key on the server

sk_app_… can publish to any channel in your app and authorize any subscription. It belongs in an environment variable your server reads and nothing else — never in NEXT_PUBLIC_*, never in client code. The browser gets the public key (pk_app_…), which can only subscribe to public- channels.

If one leaks, roll it from the dashboard. Rolling keeps the old key working for a grace window so in-flight subscriptions survive.

API

| | | |---|---| | authorizeChannel({ secret, socketId, channel, userData? }) | → Promise<{ auth, channel_data? }> | | new SocketlyServer({ secret, url?, fetch? }) | url defaults to https://api.socketly.co | | .trigger(channels, event, data, { exceptSocketId? }) | → Promise<{ delivered, remaining }> | | .channel(name) | → Promise<{ channel, kind, members, memberCount }> | | .authorizeChannel({ socketId, channel, userData? }) | same as above, using this instance's secret | | .appId | read out of the secret key |

Full documentation: docs.socketly.co

MIT