Реалтайм в Point0: канал, спейс и хэндлеры со сквозной типизацией

// engine.ts
export const engine = Engine.create({
  server: { socket: true },
})

// lib/channel.ts
import { root } from '@/lib/root'
import { getUserFromRequest } from '@/lib/auth' // ваша обычная авторизация, та же, что и в HTTP

export const appChannel = root.lets
  .channel()
  .connector(async ({ request }) => {
    // коннект это обычный HTTP-запрос: куки, заголовки, middleware на месте
    const user = await getUserFromRequest(request)
    // то, что вернул коннектор, и есть identity соединения. Она останется на сервере,
    // клиенту не видна, и будет доступна во всех дальнейших действиях на этом соединении.
    // Форма произвольная: кладите что угодно сериализуемое, хоть роль, хоть тариф,
    // хоть язык интерфейса. Тип нигде не объявляется, он выводится отсюда
    return user
      ? { authorized: true as const, id: user.id, name: user.name }
      : { authorized: false as const, id: null, name: null }
  })
  .channel()

// app.client.tsx
<appChannel.Connection>
  <RouterRoutes />
</appChannel.Connection>

// pages/feed.tsx

// сервер → клиент. Схема описывает payload, клиент прочитает его типизированным
export const postAddedHandler = appChannel.lets
  .clientHandler()
  .serverSend(
    z.object({
      id: z.string(),
      title: z.string(),
      authorId: z.string(),
      authorName: z.string(),
    }),
  )
  .clientHandler()

// ваша обычная HTTP-мутация создания поста. Из-за реалтайма в ней добавилась одна строка
export const postCreateMutation = root.lets
  .mutation()
  .input(z.object({ title: z.string().min(1) }))
  .loader(async ({ input, request }) => {
    const user = await getUserFromRequest(request)
    if (!user) throw new AppError('Только для авторизованных', { status: 401 })

    const post = await prisma.post.create({
      data: { title: input.title, authorId: user.id },
    })

    // без указания цели пуш уходит всем соединениям канала, гостям в том числе.
    // Не ждём его: доставка это сигнал, а не часть транзакции
    void postAddedHandler.sendToClient({
      id: post.id,
      title: post.title,
      authorId: user.id,
      authorName: user.name,
    })

    return post
  })
  .mutation()

const PostForm = () => {
  const create = postCreateMutation.useMutation()
  const [title, setTitle] = useState('')

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        void create
          .mutateAsync({ title })
          .then(() => setTitle(''))
          .catch((error) => alert(error.message))
      }}
    >
      <input value={title} onChange={(e) => setTitle(e.target.value)} />
      <button disabled={create.isPending}>Опубликовать</button>
    </form>
  )
}

const NewPostsBanner = () => {
  const { user } = useUser() // ваш обычный хук авторизации на клиенте
  const [fresh, setFresh] = useState<{ id: string; title: string }[]>([])

  // message типизирован схемой из .serverSend, без генерации типов
  postAddedHandler.useOnMessageFromServer(({ message }) => {
    if (message.authorId === user?.id) return // свой же пост, баннер не нужен
    setFresh((prev) => [message, ...prev])
  })

  if (fresh.length === 0) return null

  return (
    <button
      onClick={() => {
        void feedQuery.invalidateQuery() // правда живёт в квери, пуш только сказал, что она устарела
        setFresh([])
      }}
    >
      Новых постов: {fresh.length}. Показать
    </button>
  )
}

// так делать не надо
void postAddedHandler.sendToClient(payload, {
  $identity: { id: { $ne: user.id } },
})

// pages/board.tsx

const dotSchema = z.object({ x: z.number(), y: z.number(), userId: z.string() })
type Dot = z.infer<typeof dotSchema>

// без дженерика форма комнаты это пустой объект. Это частный случай: на весь проект
// в таком спейсе существует ровно одна комната. В следующих примерах на её месте будет
// нормальная структура данных, и комнат станет много
export const boardSpace = appChannel.lets
  .space()
  // .joiner это то, что вообще делает спейс доступным для входа с клиента.
  // Пускаем всех, включая гостей: смотреть доску можно всем
  .joiner(() => ({}))
  .space()

// клиент → сервер: я кликнул в точку (x, y)
export const dotPutHandler = boardSpace.lets
  .serverHandler()
  .clientSend(z.object({ x: z.number(), y: z.number() }))
  .serverReply(async ({ input, identity }) => {
    // гейт живёт здесь, на сервере, где identity можно доверять.
    // Неактивный курсор на клиенте это вежливость, а не правило
    if (!identity.authorized) {
      throw new AppError('Войдите, чтобы рисовать', { status: 401 })
    }
    const dot = { x: input.x, y: input.y, userId: identity.id }
    void dotAddedHandler.sendToClient(dot) // голый send = всем в спейсе
    return dot
  })
  .serverHandler()

// сервер → клиент: на доске появилась точка
export const dotAddedHandler = boardSpace.lets
  .clientHandler()
  .serverSend(dotSchema)
  .clientHandler()

const Board = () => {
  const membership = boardSpace.useMembership()
  const [dots, setDots] = useState<Dot[]>([])

  dotAddedHandler(membership).useOnMessageFromServer(({ message }) => {
    setDots((prev) => [...prev, message])
  })

  return (
    <div
      className="board"
      onClick={(e) => {
        const box = e.currentTarget.getBoundingClientRect()
        void dotPutHandler(membership)
          .sendToServer({
            x: (e.clientX - box.left) / box.width,
            y: (e.clientY - box.top) / box.height,
          })
          .catch((error) => alert(error.message)) // ошибка сервера прилетает сюда типизированной
      }}
    >
      {dots.map((dot, i) => (
        <span
          key={i}
          style={{ left: `${dot.x * 100}%`, top: `${dot.y * 100}%` }}
        />
      ))}
    </div>
  )
}

// pages/chat.tsx

const messageSchema = z.object({
  id: z.number(),
  chatId: z.string(),
  authorId: z.string(),
  text: z.string(),
  createdAt: z.date(),
})

export const chatSpace = appChannel.lets
  // дженерик это форма комнаты. Комната может быть любым объектом, какой удобен
  // вашему домену, { chatId } тут просто частный случай
  .space<{ chatId: string }>()
  .input(z.object({ chatId: z.string() })) // это то, что клиент передаёт в join, а не комната
  .joiner(async ({ input, identity }) => {
    // вход в комнату это и есть гейт на чтение чата
    if (!identity.authorized) {
      throw new AppError('Только для авторизованных', { status: 401 })
    }
    // возврат проверяется на соответствие форме комнаты из дженерика.
    // Лишний ключ здесь это ошибка типов, а не мелочь: сериализация комнаты
    // и есть её адрес, с лишним ключом получилась бы другая комната
    return { chatId: input.chatId }
  })
  .space()

// клиент → сервер: сохранить сообщение и разослать его комнате
export const messageSendHandler = chatSpace.lets
  .serverHandler()
  .clientSend(z.object({ text: z.string().min(1).max(1000) }))
  .serverReply(async ({ input, identity, room }) => {
    // гостя сюда не пустил joiner, но TypeScript про это не знает,
    // а лишняя проверка на сервере не грех
    if (!identity.authorized) {
      throw new AppError('Только для авторизованных', { status: 401 })
    }
    const message = await prisma.message.create({
      data: { text: input.text, chatId: room.chatId, authorId: identity.id },
    })
    // точный адрес комнаты, это pub/sub-топик, а не перебор соединений
    void messageAddedHandler.sendToClient(message, { room })
    return message // это получит отправитель в ответ на свой sendToServer
  })
  .serverHandler()

// сервер → клиент: в комнате новое сообщение
export const messageAddedHandler = chatSpace.lets
  .clientHandler()
  .serverSend(messageSchema)
  .clientHandler()

// история это обычный HTTP-квери и источник правды. У него своя проверка прав:
// сокет и HTTP это две разные двери, закрывать надо обе
export const messagesQuery = root.lets
  .query()
  .input(z.object({ chatId: z.string() }))
  .loader(async ({ input, request }) => {
    const user = await getUserFromRequest(request)
    if (!user) throw new AppError('Только для авторизованных', { status: 401 })
    return {
      messages: await prisma.message.findMany({
        where: { chatId: input.chatId },
        orderBy: { id: 'asc' },
        take: 100,
      }),
    }
  })
  .query()

const Chat = ({ chatId }: { chatId: string }) => {
  const membership = chatSpace.useMembership({ chatId })
  const { data } = messagesQuery.useQuery({ chatId })
  const [text, setText] = useState('')

  messageAddedHandler(membership).useOnMessageFromServer(({ message }) => {
    // пуш принёс готовые данные, значит запрос за ними не нужен
    messagesQuery.setQueryData({ chatId }, (old) => ({
      messages: [...(old?.messages ?? []), message],
    }))
  })

  return (
    <>
      <ul>
        {data?.messages.map((message) => (
          <li key={message.id}>{message.text}</li>
        ))}
      </ul>
      <form
        onSubmit={(e) => {
          e.preventDefault()
          setText('')
          void messageSendHandler(membership)
            .sendToServer({ text })
            .catch((error) => alert(error.message))
        }}
      >
        <input value={text} onChange={(e) => setText(e.target.value)} />
        <button disabled={membership.status !== 'joined'}>Отправить</button>
      </form>
    </>
  )
}

const membership = chatSpace.useMembership(
  { chatId },
  // вход в комнату случается заново после каждого реконнекта,
  // так что здесь же и догоняем пропущенное
  { onEnter: () => void messagesQuery.invalidateQuery({ chatId }) },
)

// lib/channel.ts
export const appChannel = root.lets
  .channel()
  .connector(/* тот же коннектор, ничего не меняется */)
  .channel({ resumable: true })

export const messageAddedHandler = chatSpace.lets
  .clientHandler()
  .serverSend(messageSchema)
  // сервер хранит последние 128 фреймов этого хэндлера на комнату
  // и доигрывает их при возврате клиента, в исходном порядке
  .clientHandler({ resumable: true })

const membership = chatSpace.useMembership(
  { chatId },
  {
    onEnter: ({ gapless }) => {
      // gapless это доказательство сервера, что ничего не потеряно:
      // либо это первый вход, либо буфер покрыл весь разрыв целиком.
      // Есть доказательство, ничего не делаем, пропущенное уже доиграно.
      // Нет, честно перечитываем историю
      if (!gapless) void messagesQuery.invalidateQuery({ chatId })
    },
  },
)

// pages/dm.tsx

// dm это direct message, личное сообщение одного пользователя другому
const dmSchema = z.object({
  id: z.number(),
  fromId: z.string(),
  toId: z.string(),
  text: z.string(),
  createdAt: z.date(),
})

export const dmSpace = appChannel.lets
  .space<{ members: string[] }>()
  .input(z.object({ withUserId: z.string() }))
  .joiner(({ input, identity }) => {
    if (!identity.authorized) {
      throw new AppError('Только для авторизованных', { status: 401 })
    }
    // sort обязателен: комната адресуется своей сериализацией
    return { members: [identity.id, input.withUserId].sort() }
  })
  .space()

export const dmAddedHandler = dmSpace.lets
  .clientHandler()
  .serverSend(dmSchema)
  .clientHandler()

// личная комната на каждого пользователя
export const userSpace = appChannel.lets
  .space<{ userId: string }>()
  // .enroller работает на сервере при подключении к каналу, до того,
  // как клиент что-либо отрендерил
  .enroller(({ identity }) =>
    // у гостя нет личной комнаты, и это нормально: вернули ничего, никуда не зачислили
    identity.authorized ? { userId: identity.id } : undefined,
  )
  .space() // .joiner отсутствует, значит с клиента в этот спейс войти нельзя вообще

export const dmBadgeHandler = userSpace.lets
  .clientHandler()
  .serverSend(z.object({ fromUserId: z.string(), preview: z.string() }))
  .clientHandler()

export const dmSendHandler = dmSpace.lets
  .serverHandler()
  .clientSend(z.object({ text: z.string().min(1) }))
  .serverReply(async ({ input, identity, room }) => {
    if (!identity.authorized) {
      throw new AppError('Только для авторизованных', { status: 401 })
    }
    const toUserId =
      room.members.find((id) => id !== identity.id) ?? identity.id

    const dm = await prisma.dm.create({
      data: { text: input.text, fromId: identity.id, toId: toUserId },
    })

    void dmAddedHandler.sendToClient(dm, { room }) // в комнату диалога
    void dmBadgeHandler.sendToClient(
      { fromUserId: identity.id, preview: dm.text.slice(0, 80) },
      { room: { userId: toUserId } }, // в личную комнату получателя
    )

    return dm
  })
  .serverHandler()

const DmBadge = () => {
  const [unread, setUnread] = useState(0)

  dmBadgeHandler.useOnMessageFromServer(({ message }) => {
    setUnread((n) => n + 1)
    toast(`${message.fromUserId}: ${message.preview}`)
  })

  return unread > 0 ? <span className="badge">{unread}</span> : null
}

const Dm = ({ withUserId }: { withUserId: string }) => {
  const membership = dmSpace.useMembership({ withUserId })
  const { data } = dmHistoryQuery.useQuery({ withUserId })
  const [text, setText] = useState('')

  dmAddedHandler(membership).useOnMessageFromServer(({ message }) => {
    dmHistoryQuery.setQueryData({ withUserId }, (old) => ({
      items: [...(old?.items ?? []), message],
    }))
  })

  return (
    <>
      <ul>
        {data?.items.map((dm) => (
          <li key={dm.id}>{dm.text}</li>
        ))}
      </ul>
      <form
        onSubmit={(e) => {
          e.preventDefault()
          setText('')
          void dmSendHandler(membership)
            .sendToServer({ text })
            .catch((error) => alert(error.message))
        }}
      >
        <input value={text} onChange={(e) => setText(e.target.value)} />
        <button disabled={membership.status !== 'joined'}>Отправить</button>
      </form>
    </>
  )
}

// pages/todos.tsx

// клиент → сервер, но выглядит как квери: тот же react-query, только транспорт сокет
export const todosHandler = appChannel.lets
  .serverHandler()
  .clientSend(z.object({ onlyOpen: z.boolean() }))
  .serverReply(async ({ input, identity }) => {
    if (!identity.authorized) {
      throw new AppError('Только для авторизованных', { status: 401 })
    }
    return {
      todos: await prisma.todo.findMany({
        where: {
          userId: identity.id,
          done: input.onlyOpen ? false : undefined,
        },
      }),
    }
  })
  .query() // вот и всё объявление
  .serverHandler()

// а это мутация. Мутация это дефолт, .mutation() можно и не писать
export const todoAddHandler = appChannel.lets
  .serverHandler()
  .clientSend(z.object({ title: z.string().min(1) }))
  .serverReply(async ({ input, identity }) => {
    if (!identity.authorized) {
      throw new AppError('Только для авторизованных', { status: 401 })
    }
    const todo = await prisma.todo.create({
      data: { title: input.title, userId: identity.id },
    })
    // всем вкладкам этого пользователя, через его личную комнату из примера 4.
    // Точный адрес, никакого перебора соединений
    void todosChangedHandler.sendToClient(undefined, {
      room: { userId: identity.id },
    })
    return todo
  })
  .mutation()
  .serverHandler()

// голый триггер без payload: «данные изменились, перечитай».
// Растёт из userSpace, то есть из личной комнаты пользователя (пример 4)
export const todosChangedHandler = userSpace.lets
  .clientHandler()
  .clientHandler()

const Todos = () => {
  const { data, isPending } = todosHandler.useSocketQuery({ onlyOpen: true })
  const add = todoAddHandler.useSocketMutation()

  todosChangedHandler.useOnMessageFromServer(() => {
    void todosHandler.invalidateSocketQuery(true) // перезапрос уедет по сокету
  })

  if (isPending) return <Spinner />

  return (
    <>
      {(data?.todos ?? []).map((todo) => (
        <div key={todo.id}>{todo.title}</div>
      ))}
      <button onClick={() => void add.mutateAsync({ title: 'Новая задача' })}>
        Добавить
      </button>
    </>
  )
}