KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #cli #codex #claude-code #dsh-plugin #mcp #react #agent #dsh #deepseek-harness

offerkit

★ 39 Open GitHub ↗

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

// 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

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README