--- name: bijection-chat description: "Evaluate and integrate the Chat component with Bijection." --- # Chat Authorization-aware human chat primitives for Bijection applications. - Package: @bijectionhq/chat - Category: Messaging - Status: Preview - License: Apache-2.0 - Bijection source (repository access required): https://github.com/bijectionhq/chat/tree/1d1ab29c707d2fa1bf124afa2c78682941c3c6b7/packages/convex-chat - Upstream: https://github.com/dciccale/convex-chat/tree/e6152c57c9e9621c19d02c58784af7348682c92b/packages/convex-chat - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/chat ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/chat.git cd chat git checkout 1d1ab29c707d2fa1bf124afa2c78682941c3c6b7 cd packages/convex-chat ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes convex-chat. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses convex-chat. Follow the installation and configuration steps exactly. # convex-chat ## Instructions Use convex-chat to authorization-aware convex component for direct and group messaging with membership enforcement, ordered sends, unread counts, presence, and attachment descriptors. This Convex component integrates directly with your backend. ### Installation ```bash npm install convex-chat ``` Current npm version: `convex-chat@0.0.1` ### Capabilities - Enforce chat membership invariants at the component boundary so your host functions never need to re-implement per-conversation access checks - Get ordered, idempotent message delivery with per-conversation sequence numbers, edit history, and deletion tombstones without building the data model yourself - Compose realtime unread counts, reply snapshots, reactions, and typing indicators into your application by wiring actor-scoped host functions - Integrate provider-neutral attachment descriptors with your own storage backend, keeping upload authorization and credential handling inside your host application ## Examples ### how to add direct messaging to a Convex app convex-chat provides a Convex component that manages conversation membership, message ordering, and unread state for direct and group conversations. You install convex-chat@next, register it in convex/convex.config.ts with app.use(chat), then expose host mutations that authenticate the caller and pass their scopeId and subjectId to the component API. Conversation creation stays in host-controlled functions so your application enforces its own relationship and policy rules before the component enforces chat invariants. ### realtime chat with presence and typing indicators in Convex convex-chat composes @convex-dev/presence internally to provide online status and typing indicators scoped to conversations. Membership is verified before any presence operation, so clients can only observe and update presence for conversations they belong to. Applications can omit the presence host wrappers entirely if presence is not required by product policy. ### how to handle file attachments in Convex chat convex-chat stores attachment descriptors in its data model but never stores binary data or provider credentials. The host application is responsible for authorizing uploads, resolving download URLs, and deleting objects. The repository includes a working Cloudflare R2 integration via @convex-dev/r2 as a reference for wiring upload grants and conversation authorization in host functions. ### unread message counts and conversation summaries in Convex convex-chat tracks exact per-conversation unread counts and exposes realtime conversation summaries through its actor-scoped API. Counts update as messages are delivered and marked read, with no polling required because the component builds on Convex's reactive query model. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by convex-chat is not needed ## Troubleshooting **Does convex-chat handle authentication or decide who can start a conversation?** No. convex-chat never decides whether two users are allowed to start a chat. The host application authenticates callers, enforces relationship and policy rules, and creates the conversation. convex-chat then enforces membership and chat invariants for every subsequent operation. Host table IDs cross the component boundary as opaque strings, so the component has no knowledge of your user model. **What version of convex-chat should I install?** Install convex-chat@next from npm. The latest tag currently points to a 0.0.1 name-reservation placeholder and does not include the implemented component. The project is in early alpha and its API and data model may change before the first stable release. **How do I register convex-chat in a Convex application?** Import the component config and register it in your convex/convex.config.ts file using app.use(chat), where chat is the default export from convex-chat/convex.config.js. Then expose host mutations and queries that authenticate the caller, derive their scopeId and subjectId, and delegate to the generated component API or the exposeChatApi wrappers. **Does convex-chat support message replies and edits?** Yes. convex-chat supports replies with deletion-safe quote snapshots, meaning the quoted content is captured at reply time and survives deletion of the original message. It also supports revision-safe edits and delete-for-everyone tombstones, so clients always receive a consistent view of message state. **Can convex-chat be used with Next.js?** The repository includes a runnable Next.js example application under apps/example that demonstrates direct messaging, presence, reactions, and Cloudflare R2 attachments. The example uses a deliberately insecure identity switcher for demo purposes and documents how to deploy to Vercel using a monorepo build configuration with a Convex deploy key. ## Resources - [npm package](https://www.npmjs.com/package/convex-chat) - [GitHub repository](https://github.com/dciccale/convex-chat) - [Live demo](https://convex-chat.dev/) - [Convex Components Directory](https://www.convex.dev/components/convex-chat) - [Convex documentation](https://docs.convex.dev)