---
name: bijection-events
description: "Evaluate and integrate the Events component with Bijection."
---

# Events

Append-only per-subject activity feed and event ledger, as a Bijection component

- Package: @bijectionhq/events
- Category: Database & Backend
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/events/tree/ba5d07de213b41de96b67f0d3e3d562f265b7f30
- Upstream: https://github.com/vllnt/convex-events/tree/e0861018422e311e8406252bb577e392dc7d85cc
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/events

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/events.git
cd events
git checkout ba5d07de213b41de96b67f0d3e3d562f265b7f30
```

## 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 @vllnt/convex-events. 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 Event Ledger. Follow the installation and configuration steps exactly.

# Event Ledger

## Instructions

@vllnt/convex-events records a chronological feed for any subject reference supplied by your app. Define event types and typed metadata to describe meaningful changes without embedding your application’s tables in the component.

record appends an event with a server timestamp. list and paginate read newest-first feeds with type and time filters. count reports whether a bounded count is exact. Configurable retention and bounded purge operations manage stored history.

Your backend decides what happened, authenticates the actor, and controls who can read the feed. This is stored event history, not a workflow executor or a tamper-proof compliance archive. Retention can remove events; record only metadata appropriate to your access and retention policy.

Maintained by [bntvllnt](https://bntvllnt.com) at [VLLNT](https://vllnt.com). Find the author on [GitHub](https://github.com/bntvllnt) and [X](https://x.com/bntvllnt).

### Installation

```bash
npm install @vllnt/convex-events
```

Current npm version: `@vllnt/convex-events@0.1.0`

## Use cases

- Team products: show project changes or workspace activity.
- Account settings: present a history of selected account actions.
- Learning apps: record completed exercises or course activity.
- Games and agent tools: retain session milestones or host-reported operation events.

## How it works

record appends an event with a server timestamp. list and paginate read newest-first feeds with type and time filters. count reports whether a bounded count is exact. Configurable retention and bounded purge operations manage stored history.

Your backend decides what happened, authenticates the actor, and controls who can read the feed. This is stored event history, not a workflow executor or a tamper-proof compliance archive. Retention can remove events; record only metadata appropriate to your access and retention policy.

## 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 Event Ledger is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40vllnt%2Fconvex-events)
- [GitHub repository](https://github.com/vllnt/convex-events)
- [Live demo](https://vllnt.com/)
- [Convex Components Directory](https://www.convex.dev/components/vllnt/convex-events)
- [Convex documentation](https://docs.convex.dev)