offerkit

KO | EN

gitlite — search

#hacktoberfest #react #llm #golang #rust #deep-learning #linux #nodejs #awesome #kubernetes #vue #awesome-list #security #mcp

(★ 39)

Agent-first, self-hostable promotion engine for coupons, loyalty, gift cards, referrals, and customer segments.

offerkit Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">OfferKit</h1>

Agent-first, dev-friendly, open-source promotion engine you self-host.

<a href="#-why-offerkit">Why OfferKit</a> ·
 <a href="#-quick-start">Quick Start</a> ·
 <a href="#-self-host">Self-Host</a> ·
 <a href="#-sdk-cli-mcp">SDK, CLI, MCP</a> ·
 <a href="#-website-and-docs">Website &amp; Docs</a> ·
 <a href="#-license">License</a>

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, scoped to products or collections
- 🧾 Stackable redemptions — apply N codes to one order atomically, all-or-nothing
- 💳 Gift cards — full ledger, partial spend, atomic rollback
- 🏆 Loyalty — programs, tiers, earning rules, points ledger, expiration
- 👥 Referrals — `{PREFIX}-{code}` codes, dual-reward conversions
- 🧩 Customer segments — JSON Logic rules with live preview
- ✅ Validation rules — debuggable, traceable; tested on every redemption
- ⚙️ 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 — every mutation with actor, before/after, IP, user agent
- 🤖 MCP server — declaratively-exposed tools with risk-level metadata
- 📜 MIT — first-party packages throughout the monorepo

## 🚀 Quick Start

Requires Docker.

```bash
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, set `OFFERKIT_PUBLIC_URL` to the exact origin that device uses before starting Compose—for example, `http://192.168.1.108:3000`. If the same instance must also accept sign-ins through other URLs, add their exact origins to the comma-separated `BETTER_AUTH_TRUSTED_ORIGINS` variable. Run `docker compose up -d --force-recreate web` after changing either value.

## 🏠 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](https://offerkit.dev/docs/self-host) 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.1.0` and `0.1.0`.

### Railway

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/offerkit?referralCode=IxSuAK)

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.1.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

[![Launch with Diploi](https://diploi.com/launch-big.svg)](https://diploi.com/launch/akshitkrnagpal/offerkit)

Create one Diploi project with a public `web` component, a private `worker` component, Postgres, and Redis. Use the same published image, `ghcr.io/offerkit/offerkit:latest`, for both components. `latest` is fine for evaluation; production deployments should pin a release tag such as `ghcr.io/offerkit/offerkit:v0.1.0`. The worker command is `node apps/worker/dist/index.js`. Wire Postgres's `DATABASE_URL` and Redis's `REDIS_URL` into both components. Set `BETTER_AUTH_SECRET`, `OFFERKIT_PUBLIC_URL`, `ADMIN_EMAIL`, and `ADMIN_PASSWORD` on `web`; set `WORKER_HEALTH_PORT=9091` on `worker`. Set the same `WEBHOOK_SECRET_ENCRYPTION_KEY` on both components.

## 📦 SDK, CLI, MCP

### TypeScript SDK

```bash
pnpm add @offerkit/sdk
```

```ts
import { createClient } from "@offerkit/sdk";

const client = createClient({
  baseUrl: "https://your-offerkit-deployment",
  apiKey: process.env.OFFERKIT_API_KEY!,
});

const result = await client.vouchers.redeem({
  params: { code: "SUMMER10" },
  body: {
    order: { amount: 9999, currency: "USD" },
    idempotencyKey: "order-42",
  },
});
```

### CLI

```bash
pnpm add -g @offerkit/cli
offerkit login --url https://your-offerkit-deployment --api-key offerkit_…
offerkit vouchers list
offerkit vouchers redeem SUMMER10 --amount 9999
```

### MCP server

Enable the hosted MCP endpoint on the `web` service to let Codex and Claude Code connect
directly to the deployment and sign in with an OfferKit account:

```bash
OFFERKIT_MCP_ENABLED=true
OFFERKIT_PUBLIC_URL=https://your-offerkit-deployment
```

The canonical endpoint is `https://your-offerkit-deployment/mcp` (`/MCP` redirects to
it). OfferKit publishes OAuth discovery metadata, dynamically registers compatible MCP
clients, and shows an account consent screen. Add it to Codex with:

```bash
codex mcp add offerkit --url https://your-offerkit-deployment/mcp
codex mcp login offerkit
```

Or add it to Claude Code, then run `/mcp` to authenticate:

```bash
claude mcp add --transport http offerkit https://your-offerkit-deployment/mcp
```

Users can revoke an authorized agent from **Settings → Agent connections**. For a local
stdio connection backed by an API key, use the published package instead:

```jsonc
{
  "mcpServers": {
    "offerkit": {
      "command": "npx",
      "args": ["-y", "@offerkit/mcp"],
      "env": {
        "OFFERKIT_API_URL": "https://your-offerkit-deployment",
        "OFFERKIT_API_KEY": "offerkit_…"
      }
    }
  }
}
```

## 🏗️ Development

Requires Node 26.5.1, pnpm 11.20.0, running Postgres, and Redis.

```bash
pnpm install
cp .env.example .env             # edit DATABASE_URL etc.
docker compose up -d postgres redis
pnpm --filter @offerkit/db push
pnpm --filter @offerkit/web dev          # web on :3000
pnpm --filter @offerkit/site dev         # public site on :4321
pnpm --filter @offerkit/worker dev       # worker on :9091
```

To test the production image shape from local source:

```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
```

```
apps/web         Next.js dashboard + REST API
apps/site        Astro marketing site + blog + Fumadocs documentation
apps/worker      Long-running Node process — runs the Redis/BullMQ job queue
packages/contract  oRPC router contract + Zod schemas (single source of truth)
packages/core    Domain logic (rules, redemption, discount, jobs, observability, email)
packages/db      Drizzle schema + client + migrations
packages/sdk     @offerkit/sdk — typed TS client
packages/cli     @offerkit/cli — `offerkit` CLI
packages/mcp     @offerkit/mcp — MCP server (stdio + http)
packages/config  ESLint + TS + Tailwind shared configs
```

```bash
pnpm -r typecheck
pnpm -r lint
pnpm -r test
```

## 🛠️ Built With

- **Next.js 16** (App Router, React 19) — dashboard + REST API
- **Postgres 17** + **Drizzle ORM** — schema, migrations, typed client
- **Redis** + **BullMQ** — default background job queue
- **Better Auth** — sessions for the dashboard, API keys for programmatic access
- **oRPC** + **Zod** — single contract for RPC, REST, and OpenAPI
- **Tailwind v4** + **shadcn/ui** — dashboard UI
- **gt-next** — i18n runtime
- **Astro** + **Fumadocs** — static website, blog, and documentation
- **OpenTelemetry** — traces, metrics, logs
- **TypeScript** strict, **MIT** first-party packages

## ✅ Quality Gates

Pull requests and pushes to `main` that affect the runtime or packages run typecheck, lint, tests, and a production build in GitHub Actions. Site-only changes are handled by Cloudflare. Local commits also run the same checks through [lefthook](https://github.com/evilmartians/lefthook):

```bash
pnpm install            # auto-runs `lefthook install`
git commit              # pre-commit runs eslint + typecheck + test
```

## 🌐 Website and docs

The public website is at <https://offerkit.dev>, with documentation at <https://offerkit.dev/docs> and the blog at <https://offerkit.dev/blog>. The Astro + Fumadocs source lives in [`apps/site/`](apps/site/).

## 🤝 Contributing

1. Fork and branch off `main`
2. `pnpm install` (hooks auto-install)
3. Make your change; the lefthook pre-commit gate runs eslint + typecheck + test
4. Open a PR

No CLA required.

## 📄 License

[MIT](./LICENSE)

## 🙏 Acknowledgments

Built on top of [Next.js](https://nextjs.org/), [Drizzle ORM](https://orm.drizzle.team/), [Better Auth](https://better-auth.com/), [oRPC](https://orpc.dev/), [Fumadocs](https://fumadocs.dev/), [gt-next](https://generaltranslation.com/), and the rest of the OSS world.

offerkit

offerkit Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

offerkit

offerkit Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README