---
name: bijection-idempotency
description: "Evaluate and integrate the Idempotency component with Bijection."
---

# Idempotency

Exactly-once idempotency key ledger for retried operations, as a Bijection component

- Package: @bijectionhq/idempotency
- Category: Durable Functions
- Status: Reference
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/idempotency/tree/e2c5bb07c1b11ecd39c7156015b1934e8c789944
- Upstream: https://github.com/vllnt/convex-idempotency/tree/7be2643b52fc390eebcedfbed85f3915b548b37b
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/idempotency

## Get the source

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

```sh
git clone https://github.com/bijectionhq/idempotency.git
cd idempotency
git checkout e2c5bb07c1b11ecd39c7156015b1934e8c789944
```

## 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-idempotency. 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 Idempotency Keys. Follow the installation and configuration steps exactly.

# Idempotency Keys

## Instructions

@vllnt/convex-idempotency helps your backend recognize repeated attempts at the same operation. A key identifies the work, an active claim coordinates attempts, and a stored result lets retries return the previous outcome.

begin returns a fresh claim, an inflight state, or a completed result. complete stores a typed outcome and reports lost or expired claims. Configure separate TTLs for active claims and completed results; scopes namespace keys by tenant or operation.

Your application authorizes the operation and must coordinate business writes with the claim lifecycle. This ledger does not make arbitrary external side effects exactly-once: use provider idempotency and recovery logic where needed. Once retention expires, a key may be used again.

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-idempotency
```

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

## Use cases

- Webhook handlers: recognize repeated provider delivery IDs before applying a change.
- Mobile apps: replay a saved response when a client retries after losing its connection.
- Forms and checkout flows: protect host-side mutations from duplicate submissions.
- Agent tools and integrations: reuse an operation key when a caller retries an uncertain request.

## How it works

begin returns a fresh claim, an inflight state, or a completed result. complete stores a typed outcome and reports lost or expired claims. Configure separate TTLs for active claims and completed results; scopes namespace keys by tenant or operation.

Your application authorizes the operation and must coordinate business writes with the claim lifecycle. This ledger does not make arbitrary external side effects exactly-once: use provider idempotency and recovery logic where needed. Once retention expires, a key may be used again.

## 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 Idempotency Keys is not needed

## Resources

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