API Reference

Server API

Everything exported from hotpipe/server. This is the server-side SDK for auth, event publishing, and access revocation.

createPipeHandler(config)

Returns { POST } for your catch-all route handler.

Name
secret
Type
string
Description
Shared signing secret. Required.
Name
authorize
Type
(req: Request) => Promise<AuthResult | null>
Description
Your auth logic. Return the user's ID and pipe permissions to grant access, or null to deny. Required.
Name
tokenExpiry
Type
number
Description
Token lifetime in seconds. Defaults to 3600.

// app/api/realtime/[...all]/route.ts
import { createPipeHandler } from 'hotpipe/server';

export const { POST } = createPipeHandler({
  secret: process.env.HOTPIPE_SECRET!,
  authorize: async (req) => {
    const { session } = await getAuth(req);
    if (!session) return null;

    return {
      userId: session.userId,
      pipes: {
        'team-chat': { subscribe: true, publish: true },
      },
    };
  },
  tokenExpiry: 3600,
});

createPipePublisher(config)

Returns { pipe } for server-side event publishing.

Name
secret
Type
string
Description
Your Hotpipe secret. Required.
Name
events
Type
Record<string, ZodType>
Description
Zod schemas for your events. Required.

publisher.pipe(name)

Returns { publish } scoped to a specific pipe. Unlike the client-side publish, this is async — it makes an HTTP request to the Hotpipe API and will throw if the request fails.

publish(event, data, options?)

Name
event
Type
string
Description
The event name, matching a key in your events schema.
Name
data
Type
object
Description
Event payload, validated against the Zod schema.
Name
options.sender
Type
string
Description
Identity to attach as the verified sender. Receiving clients see this in metadata.sender. Defaults to null.

import { createPipePublisher } from 'hotpipe/server';

const realtime = createPipePublisher({
  secret: process.env.HOTPIPE_SECRET!,
  events: realtimeEvents,
});

// publish to a pipe
const teamChat = realtime.pipe('team-chat');

await teamChat.publish('message.created', {
  id: message.id,
  text: message.text,
  userId: message.userId,
  createdAt: message.createdAt,
});

// with explicit sender
await teamChat.publish('message.created', data, { sender: 'bot-assistant' });

createPipeAdmin(config)

Returns { revoke, revokeAll, revokeBatch } for real-time access revocation.

Name
secret
Type
string
Description
Your Hotpipe secret. Required.

pipeAdmin.revoke(userId, pipe, options?)

Revoke a user's access to one or more pipes. The user is immediately unsubscribed and receives a system event. Returns a Promise<void>.

Name
userId
Type
string
Description
The user to revoke. Required.
Name
pipe
Type
string | string[]
Description
Pipe name or array of pipe names to revoke. Required.
Name
options.ttl
Type
number
Description
Time in seconds before the revocation expires. Defaults to 3600.

pipeAdmin.revokeAll(userId, options?)

Revoke a user's access to all pipes. Used for account suspension or termination. Returns a Promise<void>.

Name
userId
Type
string
Description
The user to revoke. Required.
Name
options.ttl
Type
number
Description
Time in seconds before the revocation expires. Defaults to 3600.

pipeAdmin.revokeBatch(revocations, options?)

Revoke multiple user+pipe combinations in a single call. Used when deleting a channel or removing a group of users. Returns a Promise<void>.

Name
revocations
Type
{ userId: string, pipe: string }[]
Description
User+pipe pairs to revoke. Required.
Name
options.ttl
Type
number
Description
Time in seconds before the revocations expire. Defaults to 3600.

import { createPipeAdmin } from 'hotpipe/server';

const pipeAdmin = createPipeAdmin({
  secret: process.env.HOTPIPE_SECRET!,
});

// revoke access to a single pipe
await pipeAdmin.revoke('user-123', 'room-abc');

// revoke access to multiple pipes
await pipeAdmin.revoke('user-123', ['room-abc', 'room-def']);

// revoke access to all pipes (account suspension)
await pipeAdmin.revokeAll('user-123');

// batch revocation (e.g., deleting a channel)
await pipeAdmin.revokeBatch([
  { userId: 'user-123', pipe: 'room-abc' },
  { userId: 'user-456', pipe: 'room-abc' },
]);