next-charge

Token-bucket charge system for Next.js API routes backed by Redis. Prevents unbounded spend from public demos.

Install

pnpm add next-charge

Quick start

Define your charge system

// lib/charge.ts
import { createChargeSystem } from "next-charge";
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

export const {
  withCharge,
  getChargeState,
  getAllChargeStates,
  topOff,
  checkCharges,
  chargeStatusHandler,
  checkHandler,
} = createChargeSystem({
  redis,
  pools: [
    { id: "generate-image", maxCharges: 5, rechargeIntervalHours: 2 },
    { id: "describe-image", maxCharges: 20, rechargeIntervalHours: 0.5 },
  ],
});

Wrap your API routes

// app/api/generate/route.ts
import { withCharge } from "@/lib/charge";

export const POST = withCharge("generate-image", async (req: Request) => {
  const body = await req.json();
  // ... your handler logic
  return Response.json({ success: true });
});

When charges are depleted, the wrapper returns a 429 response:

{
  "error": "out_of_charge",
  "retryAfterMs": 3600000,
  "poolId": "generate-image"
}

A Retry-After header (in seconds) is also set.

If Redis is unreachable, the wrapper returns a 503 with { "error": "service_unavailable" } (fail-closed).

Add status endpoints (optional)

// app/api/usage/route.ts
import { chargeStatusHandler } from "@/lib/charge";

export const GET = chargeStatusHandler();

// app/api/usage/check/route.ts
import { checkHandler } from "@/lib/charge";

export const GET = checkHandler();

GET /api/usage returns all pool states. GET /api/usage/check?pools=generate-image,describe-image returns a quick availability check:

{ "ok": true, "pools": [{ "id": "generate-image", "available": true }, ...] }

Client-side hook

import { useChargeFetch } from "next-charge/client";

const chargeFetch = useChargeFetch({
  onOutOfCharge: (body, retryStr) => {
    alert(`Out of charges for ${body.poolId}. Recharges in ${retryStr}.`);
  },
});

const res = await chargeFetch("/api/generate", { method: "POST", body: JSON.stringify(data) });

useChargeFetch wraps fetch() and intercepts 429 responses with error: "out_of_charge". It calls your onOutOfCharge callback with the parsed body and a human-readable retry string (e.g. "45m", "2h 15m"). The original Response is still returned so you can handle other errors normally.

Configuration

createChargeSystem(config)

Field	Type	Default	Description
redis	ChargeRedis	required	Redis client instance
pools	ChargePoolConfig[]	required	Array of charge pool definitions
keyPrefix	string	"charge:"	Prefix for Redis keys
devBypass	boolean	false	Skip consumption (reads still work if Redis is available)

ChargePoolConfig

Field	Type	Default	Description
id	string	required	Unique pool identifier
maxCharges	number	required	Maximum accumulated charges
rechargeIntervalHours	number	required	Hours to regenerate one charge
label	string	id	Human-readable label for status endpoints
group	string	""	Grouping key for dashboard sections

Redis compatibility

next-charge needs only three methods from your Redis client:

interface ChargeRedis {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<unknown>;
  eval(script: string, keys: string[], args: string[]): Promise<unknown>;
}

This is directly compatible with @upstash/redis and @vercel/kv. For ioredis, wrap with a thin adapter:

import Redis from "ioredis";

const raw = new Redis(process.env.REDIS_URL!);
const redis = {
  get: (k: string) => raw.get(k),
  set: (k: string, v: string) => raw.set(k, v) as Promise<unknown>,
  eval: (script: string, keys: string[], args: string[]) =>
    raw.eval(script, keys.length, ...keys, ...args),
};

How it works

Each pool tracks { current, lastUpdatedAt } in a single Redis key. Recharge is passive and time-based -- no background jobs or cron required.

On consume, an atomic Lua script computes how many charges have accumulated since lastUpdatedAt, adds them to current (capped at maxCharges), then decrements by one. If no charges are available, it returns retryAfterMs without writing.

lastUpdatedAt advances by exact interval multiples (not wall-clock time) to preserve partial recharge progress. A missing key initializes as full. Redis failures fail-closed (503). When devBypass is true, consumption always succeeds.

License

MIT