BirrJS Core

Ethiopian payment billing and subscription management for TypeScript

GitHub · Documentation · Issues

About

BirrJS sits between your app and local/regional payment providers (Chapa, etc.) providing a unified API for subscriptions, entitlements, and billing.Tailored for Ethiopian payment providers and similar markets.

Features

• Subscription management with automatic status tracking
• Entitlement/feature-gating system
• Multi-tenant customer management
• Cron-based subscription expiry and reminder sweeps
• Provider-agnostic adapter pattern (Chapa included)
• Plugin system for extensibility
• TypeScript-first with full type safety
• PostgreSQL + Drizzle ORM

Installation

npm install @birrjs/core
# or
pnpm add @birrjs/core

Quick Start

import { createBirr, feature, plan } from "@birrjs/core";
import { chapa } from "@birrjs/chapa";

const messages = feature({ id: "messages", type: "metered" });

const free = plan({
  id: "free",
  name: "Free",
  default: true,
  includes: [messages({ limit: 100, reset: "month" })],
});

const pro = plan({
  id: "pro",
  name: "Pro",
  price: { amount: 29, interval: "monthly" },
  includes: [messages({ limit: 5000, reset: "month" })],
});

const birr = createBirr({
  database: process.env.DATABASE_URL!,
  provider: chapa({
    secretKey: process.env.CHAPA_SECRET_KEY!,
    webhookSecret: process.env.CHAPA_WEBHOOK_SECRET!,
    callbackUrl: process.env.CALLBACK_URL!,
    returnUrl: process.env.RETURN_URL!,
  }),
  plans: [free, pro],
  identify: async (request) => {
    const session = await auth.api.getSession({ headers: request.headers });
    if (!session) return null;
    return { customerId: session.user.id, email: session.user.email };
  },
});

License

MIT