Server API

// find-or-create a 1:1 conversation between two users
const conversation = await chat.api.getOrCreateConversation({
  userId: "alice",
  otherUserId: "bob",
});

// send a message
const message = await chat.api.sendMessage({
  userId: "alice",
  conversationId: conversation.id,
  body: "hey bob!",
});

// quote-reply to it - a flat pointer, not a thread
const reply = await chat.api.sendMessage({
  userId: "bob",
  conversationId: conversation.id,
  body: "hey alice!",
  replyToMessageId: message.id,
});
reply.replyTo; // { id, senderId, excerpt: "hey bob!", deleted: false }

// react (idempotent both ways; returns the message with its whole set)
const reacted = await chat.api.addReaction({
  userId: "bob",
  messageId: message.id,
  emoji: "👍",
});
reacted.reactions; // [{ emoji: "👍", count: 1, userIds: ["bob"] }]
await chat.api.removeReaction({ userId: "bob", messageId: message.id, emoji: "👍" });

// mention participants - ids you supply, never parsed out of the body
const mentioning = await chat.api.sendMessage({
  userId: "alice",
  conversationId: conversation.id,
  body: "@bob can you look?",
  mentions: ["bob"], // must be current participants, else MENTION_NOT_PARTICIPANT
});
mentioning.mentions; // ["bob"] - a set; treat the order as unspecified

// forward it somewhere else - a COPY, with you as sender
const forwarded = await chat.api.forwardMessage({
  userId: "alice",
  messageId: message.id,
  toConversationId: "conv_7", // any conversation alice can write to
});
forwarded.forwardedFrom; // { messageId, conversationId, senderId } - frozen, three ids
// Editing or deleting `message` now changes nothing about `forwarded`.

// search participant conversations (case-insensitive, canonical token matching, ranked)
const search = await chat.api.searchMessages({
  userId: "bob",
  query: "hello",
  limit: 50,
});
// Throws SEARCH_UNSUPPORTED when storage adapter has no search capability.

// paginate history (newest first)
const { messages, nextCursor } = await chat.api.listMessages({
  userId: "bob",
  conversationId: conversation.id,
  limit: 50,
});

// durable read-state
await chat.api.markRead({
  userId: "bob",
  conversationId: conversation.id,
  messageId: message.id,
});

// alice becomes the group's first admin; bob and carol join as members.
// Calling this twice creates TWO groups - store the id you get back.
const group = await chat.api.createGroupConversation({
  userId: "alice",
  userIds: ["bob", "carol"],
  name: "Launch",
});
group.type; // "group" - and pairKey is null, since only DMs have one

// Membership writes are admin-only and idempotent; each returns the whole
// conversation, so overwrite your cached copy rather than merging.
await chat.api.addParticipants({
  userId: "alice",
  conversationId: group.id,
  userIds: ["dave"],
});
await chat.api.setParticipantRole({
  userId: "alice",
  conversationId: group.id,
  targetUserId: "bob",
  role: "admin",
});

// Anyone can remove themselves - that is "leave", and needs no admin rights.
await chat.api.removeParticipant({
  userId: "dave",
  conversationId: group.id,
  targetUserId: "dave",
});

// Rename, or pass null to clear the title.
await chat.api.updateConversation({
  userId: "alice",
  conversationId: group.id,
  name: "Launch week",
});

// Mint a link. Every option is optional: no arguments beyond the ids means a
// link that never expires and admits unlimited people.
const invite = await chat.api.createInvite({
  userId: "alice",
  conversationId: group.id,
  expiresInSeconds: 86_400,
  maxUses: 5,
});
invite.code; // 43 URL-safe chars - build your own /join/:code page around it

// The landing page. Deliberately NOT getConversation: a non-member may call
// this, so it carries a participant count and never any user ids.
const preview = await chat.api.getInvitePreview({ userId: "erin", code: invite.code });
preview.alreadyParticipant; // false - render "Join", not "Open"

// Redeeming. Branch on `status`, not on which field came back null.
const result = await chat.api.acceptInvite({ userId: "erin", code: invite.code });
if (result.status === "joined") {
  result.conversation; // the group, now including erin
} else {
  result.joinRequest; // requiresApproval was true - an admin must resolve it
}

// Clicking the link twice is harmless and costs the invite nothing: erin gets
// the conversation back, even once the link is out of uses.

await chat.api.requestToJoin({
  userId: "frank",
  conversationId: group.id,
  message: "I'm on the design team", // optional note for the admins
});
// Already a participant? Throws ALREADY_PARTICIPANT - there is no join request
// that honestly represents "you're already in".

// The queue defaults to pending. No event fires when a request arrives, so
// admins poll this.
const queue = await chat.api.listJoinRequests({ userId: "alice", conversationId: group.id });

// Resolved by user id, not request id: one request per user per group.
const { joinRequest, conversation } = await chat.api.resolveJoinRequest({
  userId: "alice",
  conversationId: group.id,
  targetUserId: "frank",
  decision: "approve", // "deny" leaves conversation null and keeps the row
});

// Publish an existing group, or pass the same two fields to
// createGroupConversation. Admin-only (canManage, not canInvite) - loosening
// who may invite must not also decide who may expose the group to everyone.
const channel = await chat.api.updateConversation({
  userId: "alice",
  conversationId: group.id,
  visibility: "public",
  joinPolicy: "open", // omit and it stays "approval" - the recoverable default
});

// The directory. Thin previews, like an invite preview and for the same
// reason: strangers read this, so it carries a participant COUNT, never ids.
const { channels, nextCursor } = await chat.api.listPublicConversations({
  userId: "grace",
  limit: 20, // most-recently-active first, same keyset paging as listConversations
});
channels[0]?.alreadyParticipant; // render "Open" / "Pending" / "Join" from these
channels[0]?.requestPending;

// Joining. Same discriminated union as acceptInvite - branch on `status`.
const result = await chat.api.joinConversation({
  userId: "grace",
  conversationId: channel.id,
  message: "found you in the directory", // only used on an "approval" channel
});
if (result.status === "joined") result.conversation;
else result.joinRequest; // lands in the same queue, with inviteCode: null

export const chat = chatpack({
  storage,
  auth,
  // Your identity store, your query. Return false for "no such user".
  userExists: async (userId) =>
    Boolean(
      await db.query.users.findFirst({
        where: eq(users.id, userId),
      }),
    ),
});

import { ChatpackError } from "@chatpack/core";

try {
  await chat.api.getConversation({ userId, conversationId });
} catch (err) {
  if (err instanceof ChatpackError && err.code === "CONVERSATION_NOT_FOUND") {
    // handle the missing conversation
  } else {
    throw err;
  }
}