OfferKit is open-source promotion infrastructure for coupons, gift cards, loyalty, referrals, customer segments, and validation rules. It ships with a dashboard, REST API, TypeScript SDK, CLI, and MCP server, and runs from one Docker image for self-hosted deployments.
🤖 Why OfferKit
Agent-first. The MCP server is a first-class surface, not bolted on. Every mutating endpoint declares its risk level (safe / mutating / destructive) so LLM hosts can render the right confirmation. New procedures opt into MCP exposure declaratively via .meta() — no separate package to update.
Dev-friendly. The typed SDK is derived directly from the oRPC contract, so client types stay in lockstep with the server with zero codegen. Strict TypeScript, linted against explicit any, with typed contracts at API boundaries. The public website, blog, and documentation share an Astro + Fumadocs workspace that deploys as a static site. Local-first dev with Docker Compose, plus CI and lefthook quality gates.
Open source. MIT-licensed first-party packages. No CLA required. No commercial features paywalled. Built on top of permissive OSS.
Self-hostable. One docker compose up brings up web + worker + Postgres + Redis from ghcr.io/offerkit/offerkit. Railway uses the same published image for both services; no GitHub source deploy required. OpenTelemetry-ready out of the box for any OTLP backend.
✨ Features
- 🎟️ Discount engine — fixed-amount, percentage, with optional caps, with product and collection eligibility rules; calculation uses the submitted order total
- 🧾 Stackable redemptions — apply N codes to one order atomically, all-or-nothing
- 💳 Gift cards — balance ledger and spend up to the order amount
- 🏆 Loyalty — tiers, points ledger, per-earning expiry; earning rules are reporting labels
- 👥 Referrals — stable advocate codes; rewards for both the advocate and the friend
- 🧩 Customer segments — JSON Logic audience previews; runtime targeting uses attached rules
- ✅ Validation rules — attach to campaigns or promotion tiers and check each decision
- ⚙️ Background jobs — Redis/BullMQ by default, with a Postgres fallback when Redis is not configured
- 🔭 Observability — OpenTelemetry traces, metrics, logs out of the box
- 🔐 Audit log — mutation requests with actor, submitted input, IP, and user agent
- 🤖 MCP server — declaratively-exposed tools with risk-level metadata
- 📜 MIT — first-party packages throughout the monorepo
New to promotion engines? Start with How OfferKit works
and How objects connect. A campaign
groups the offer, a voucher is a discount or gift-value code, loyalty tracks points, and
referrals link an advocate to the friend they invite. The glossary
explains the terms used below.
🚀 Quick Start
Requires Docker.
git clone https://github.com/offerkit/offerkit.git
cd offerkit
cp .env.example .env
docker compose up
Visit http://localhost:3000 and sign in with the ADMIN_EMAIL / ADMIN_PASSWORD in .env. The example defaults work locally; edit them before deploying. The first sign-in forces a password change.
To open OfferKit from another device, browse directly to the server's LAN address—for example, http://192.168.1.108:3000. Current source needs no origin configuration for direct localhost or LAN access. The published v0.2.0 image requires an explicit LAN origin in BETTER_AUTH_TRUSTED_ORIGINS; see the version-specific setup note. Set OFFERKIT_PUBLIC_URL when the deployment has a canonical external URL, reverse proxy, OAuth clients, or hosted MCP. If that configured deployment must also accept authentication from other browser origins, add their exact origins to BETTER_AUTH_TRUSTED_ORIGINS.
🏠 Self-Host
Docker compose
The docker-compose.yml brings up web + worker + postgres + redis. Both runtime services use the same published image, ghcr.io/offerkit/offerkit. Migrations run automatically on web boot. Background jobs use Redis/BullMQ when REDIS_URL is set, with a Postgres fallback otherwise. See the self-hosting guide for env vars and tuning.
Image channels:
edge follows the latest main commit.latest follows the newest stable image version.- Version tags are published as both
v0.2.0 and 0.2.0.
Railway
In one Railway project, create Postgres and Redis, then create two Docker Image services from ghcr.io/offerkit/offerkit:latest. latest is fine for evaluation; production deployments should pin a release tag such as ghcr.io/offerkit/offerkit:v0.2.0. The public web service uses the default command. The private worker service overrides the command to node apps/worker/dist/index.js and should not have a public domain. Reference Postgres's DATABASE_URL and Redis's REDIS_URL into both app services. Set BETTER_AUTH_SECRET, OFFERKIT_PUBLIC_URL, ADMIN_EMAIL, and ADMIN_PASSWORD on the web service. Set the same WEBHOOK_SECRET_ENCRYPTION_KEY (generate one with openssl rand -base64 32) on both services.
Diploi
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
