@haruhimemoe/next-kit 0.1.0

package/dist/mongo/duplicate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file src/mongo/duplicate.ts
+ * @desc Whether a MongoDB error is a duplicate key (E11000): two upserts racing to insert the
+ *       same _id, or a unique index that existing rows break. Pure, no driver import.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** MongoDB's duplicate key error code. */
+export declare const DUPLICATE_KEY = 11000;
+/**
+ * @function isDuplicateKeyError
+ * @param error {unknown} anything thrown
+ * @returns {boolean} true when it carries code 11000
+ */
+export declare const isDuplicateKeyError: (error: unknown) => boolean;

package/dist/mongo/duplicate.js

@@ -0,0 +1,16 @@
+/**
+ * @file src/mongo/duplicate.ts
+ * @desc Whether a MongoDB error is a duplicate key (E11000): two upserts racing to insert the
+ *       same _id, or a unique index that existing rows break. Pure, no driver import.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** MongoDB's duplicate key error code. */
+export const DUPLICATE_KEY = 11000;
+/**
+ * @function isDuplicateKeyError
+ * @param error {unknown} anything thrown
+ * @returns {boolean} true when it carries code 11000
+ */
+export const isDuplicateKeyError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === DUPLICATE_KEY;

package/dist/mongo/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file src/mongo/index.ts
+ * @desc @haruhimemoe/next-kit/mongo: the connect-once MongoDB client with Mongoose on the same
+ *       client, index declaration and duplicate-safe creation, the collection-name constants
+ *       pattern, and the duplicate key check. Server only.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { createMongo, DEFAULT_MAX_POOL_SIZE, DEFAULT_SERVER_SELECTION_TIMEOUT_MS, type Mongo, type MongoOptions, } from "./client.js";
+export { defineCollections } from "./collections.js";
+export { DUPLICATE_KEY, isDuplicateKeyError } from "./duplicate.js";
+export { ensureIndexes, type IndexReport, type IndexSpec, indexName, ttlIndex, } from "./indexes.js";

package/dist/mongo/index.js

@@ -0,0 +1,13 @@
+/**
+ * @file src/mongo/index.ts
+ * @desc @haruhimemoe/next-kit/mongo: the connect-once MongoDB client with Mongoose on the same
+ *       client, index declaration and duplicate-safe creation, the collection-name constants
+ *       pattern, and the duplicate key check. Server only.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { createMongo, DEFAULT_MAX_POOL_SIZE, DEFAULT_SERVER_SELECTION_TIMEOUT_MS, } from "./client.js";
+export { defineCollections } from "./collections.js";
+export { DUPLICATE_KEY, isDuplicateKeyError } from "./duplicate.js";
+export { ensureIndexes, indexName, ttlIndex, } from "./indexes.js";

package/dist/mongo/indexes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file src/mongo/indexes.ts
+ * @desc Index declaration and creation for collections Mongoose doesn't manage. Each index builds
+ *       on its own over whatever data is there: a unique one that existing duplicates break is
+ *       skipped and logged with up to 10 of the duplicate keys (never for a secret key, like a
+ *       session token), any other failure is logged, and the rest still build. Nothing throws:
+ *       a missing index must not take sign-in or the site down. createIndex is a no-op when the
+ *       index already exists. Moved from pools (src/lib/db-indexes.ts), whose auth indexes got
+ *       this treatment; the TTL indexes both apps declared use it too.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { Db, Document } from "mongodb";
+/** One index to build. */
+export type IndexSpec = {
+    collection: string;
+    /** Field order matters; 1 ascending, -1 descending. */
+    key: Record<string, 1 | -1>;
+    /** Defaults to MongoDB's own (`field_1_other_-1`). */
+    name?: string;
+    unique?: boolean;
+    /** A TTL index: documents go this long after the key's date (0: at it). */
+    expireAfterSeconds?: number;
+    partialFilterExpression?: Document;
+    /** The key is a credential: never log its values. */
+    secret?: boolean;
+};
+/** What ensureIndexes did, by index name. */
+export type IndexReport = {
+    built: string[];
+    skipped: string[];
+};
+/**
+ * @function indexName
+ * @param spec {IndexSpec} an index
+ * @returns {string} its name, or the one MongoDB gives it (`osuId_1`, `a_1_b_-1`)
+ */
+export declare const indexName: (spec: IndexSpec) => string;
+/**
+ * @function ttlIndex
+ * @param collection {string} the collection
+ * @param field {string} the date field
+ * @param expireAfterSeconds {number} how long after that date a document goes (default 0)
+ * @param name {string | undefined} the index name (default MongoDB's)
+ * @returns {IndexSpec} a TTL index on that field
+ */
+export declare const ttlIndex: (collection: string, field: string, expireAfterSeconds?: number, name?: string) => IndexSpec;
+/**
+ * @function ensureIndexes
+ * @param db {Db} the database
+ * @param specs {readonly IndexSpec[]} the indexes to build
+ * @returns {Promise<IndexReport>} each index built, or skipped and logged (never thrown)
+ */
+export declare const ensureIndexes: (db: Db, specs: readonly IndexSpec[]) => Promise<IndexReport>;

package/dist/mongo/indexes.js

@@ -0,0 +1,81 @@
+/**
+ * @file src/mongo/indexes.ts
+ * @desc Index declaration and creation for collections Mongoose doesn't manage. Each index builds
+ *       on its own over whatever data is there: a unique one that existing duplicates break is
+ *       skipped and logged with up to 10 of the duplicate keys (never for a secret key, like a
+ *       session token), any other failure is logged, and the rest still build. Nothing throws:
+ *       a missing index must not take sign-in or the site down. createIndex is a no-op when the
+ *       index already exists. Moved from pools (src/lib/db-indexes.ts), whose auth indexes got
+ *       this treatment; the TTL indexes both apps declared use it too.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { isDuplicateKeyError } from "./duplicate.js";
+/**
+ * @function indexName
+ * @param spec {IndexSpec} an index
+ * @returns {string} its name, or the one MongoDB gives it (`osuId_1`, `a_1_b_-1`)
+ */
+export const indexName = (spec) => spec.name ??
+    Object.entries(spec.key)
+        .map(([field, order]) => `${field}_${order}`)
+        .join("_");
+/**
+ * @function ttlIndex
+ * @param collection {string} the collection
+ * @param field {string} the date field
+ * @param expireAfterSeconds {number} how long after that date a document goes (default 0)
+ * @param name {string | undefined} the index name (default MongoDB's)
+ * @returns {IndexSpec} a TTL index on that field
+ */
+export const ttlIndex = (collection, field, expireAfterSeconds = 0, name) => ({
+    collection,
+    key: { [field]: 1 },
+    expireAfterSeconds,
+    ...(name === undefined ? {} : { name }),
+});
+/** Up to 10 key values held by more than one row, with how many rows hold each. */
+const duplicatesOf = async (db, spec) => {
+    const group = Object.fromEntries(Object.keys(spec.key).map((field) => [field, `$${field}`]));
+    return db
+        .collection(spec.collection)
+        .aggregate([
+        { $group: { _id: group, rows: { $sum: 1 } } },
+        { $match: { rows: { $gt: 1 } } },
+        { $limit: 10 },
+    ])
+        .toArray();
+};
+const buildIndex = async (db, spec) => {
+    const name = indexName(spec);
+    const { collection, key, secret, ...options } = spec;
+    try {
+        await db.collection(collection).createIndex(key, { ...options, name });
+        return true;
+    }
+    catch (error) {
+        if (!isDuplicateKeyError(error)) {
+            console.error(`db: couldn't create ${name}`, secret ? "" : error);
+            return false;
+        }
+        const found = secret ? [] : await duplicatesOf(db, spec).catch(() => []);
+        console.error(`db: ${collection} has rows sharing ${Object.keys(key).join(", ")}, so ${name} wasn't built. ` +
+            "Merge or remove the extra rows; it builds on the next start.", secret ? "" : JSON.stringify(found));
+        return false;
+    }
+};
+/**
+ * @function ensureIndexes
+ * @param db {Db} the database
+ * @param specs {readonly IndexSpec[]} the indexes to build
+ * @returns {Promise<IndexReport>} each index built, or skipped and logged (never thrown)
+ */
+export const ensureIndexes = async (db, specs) => {
+    const results = await Promise.all(specs.map((spec) => buildIndex(db, spec)));
+    const report = { built: [], skipped: [] };
+    specs.forEach((spec, index) => {
+        report[results[index] ? "built" : "skipped"].push(indexName(spec));
+    });
+    return report;
+};

package/dist/server/body.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file src/server/body.ts
+ * @desc Reading what a route is sent. parseJsonBody takes application/json only (a cross-site
+ *       form can't send it without a CORS preflight), at most 16 KB unless the route gives its
+ *       own cap, and a zod schema (pass z.strictObject so unknown keys are refused); a schema
+ *       refusal's code is the one its refinement names in `params.code`, like content_filter.
+ *       parseIdList reads `?ids=1,2,3`. Moved from pools (src/lib/api.ts), which had packs'
+ *       version plus the cap option, the named codes and a strict id parser.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { z } from "zod";
+/** The default body cap: a 64-slot pack or an admin edit is under 3 KB of JSON. */
+export declare const MAX_BODY_BYTES = 16384;
+/** What parseJsonBody gives back: the parsed data, or an error answer ready to send. */
+export type ParsedBody<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    response: Response;
+};
+/** parseJsonBody's options. */
+export type ParseJsonBodyOptions = {
+    /** The 413 message (default "That request is too large."). */
+    tooLarge?: string;
+    /** The cap in bytes (default MAX_BODY_BYTES). */
+    maxBytes?: number;
+};
+/**
+ * @function parseJsonBody
+ * @param request {Request} incoming request
+ * @param schema {z.ZodType} what the body must be
+ * @param options {ParseJsonBodyOptions} the 413 message and the cap
+ * @returns {Promise<ParsedBody<z.output<T>>>} parsed data, or a 415, 413 or 400 answer: the
+ *          400's message is the first issue's, its code the refinement's `params.code` if it's a
+ *          string, else bad_request
+ */
+export declare const parseJsonBody: <T extends z.ZodType>(request: Request, schema: T, { tooLarge, maxBytes }?: ParseJsonBodyOptions) => Promise<ParsedBody<z.output<T>>>;
+/** The largest id an osu! beatmap (or any 32-bit signed id) can have. */
+export declare const MAX_ID = 2147483647;
+/** parseIdList's options. */
+export type ParseIdListOptions = {
+    /** At most this many ids. */
+    max: number;
+    /** Whether one id is acceptable (default: 1 to MAX_ID). */
+    isValid?: (id: number) => boolean;
+};
+/**
+ * @function parseIdList
+ * @param raw {string | null} a comma-separated query value, like `?ids=`
+ * @param options {ParseIdListOptions} the most ids and the per-id check
+ * @returns {number[] | null} 1 to `max` ids in the order sent, each 1 to 10 plain digits and
+ *          valid; null for anything else (an empty part, spaces, signs, hex, exponents, too many)
+ */
+export declare const parseIdList: (raw: string | null, { max, isValid }: ParseIdListOptions) => number[] | null;

package/dist/server/body.js

@@ -0,0 +1,74 @@
+/**
+ * @file src/server/body.ts
+ * @desc Reading what a route is sent. parseJsonBody takes application/json only (a cross-site
+ *       form can't send it without a CORS preflight), at most 16 KB unless the route gives its
+ *       own cap, and a zod schema (pass z.strictObject so unknown keys are refused); a schema
+ *       refusal's code is the one its refinement names in `params.code`, like content_filter.
+ *       parseIdList reads `?ids=1,2,3`. Moved from pools (src/lib/api.ts), which had packs'
+ *       version plus the cap option, the named codes and a strict id parser.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { jsonError } from "./errors.js";
+/** The default body cap: a 64-slot pack or an admin edit is under 3 KB of JSON. */
+export const MAX_BODY_BYTES = 16_384;
+/**
+ * @function parseJsonBody
+ * @param request {Request} incoming request
+ * @param schema {z.ZodType} what the body must be
+ * @param options {ParseJsonBodyOptions} the 413 message and the cap
+ * @returns {Promise<ParsedBody<z.output<T>>>} parsed data, or a 415, 413 or 400 answer: the
+ *          400's message is the first issue's, its code the refinement's `params.code` if it's a
+ *          string, else bad_request
+ */
+export const parseJsonBody = async (request, schema, { tooLarge = "That request is too large.", maxBytes = MAX_BODY_BYTES } = {}) => {
+    const type = request.headers.get("content-type")?.toLowerCase() ?? "";
+    if (!type.startsWith("application/json")) {
+        return { ok: false, response: jsonError(415, "Send the request as JSON.") };
+    }
+    // Refuse an honest oversized body before reading it; still measure what actually arrived.
+    if (Number(request.headers.get("content-length") ?? 0) > maxBytes) {
+        return { ok: false, response: jsonError(413, tooLarge) };
+    }
+    const text = await request.text();
+    if (new TextEncoder().encode(text).length > maxBytes) {
+        return { ok: false, response: jsonError(413, tooLarge) };
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, response: jsonError(400, "That request wasn't valid JSON.") };
+    }
+    const parsed = schema.safeParse(body);
+    if (parsed.success)
+        return { ok: true, data: parsed.data };
+    const issue = parsed.error.issues[0];
+    const named = issue?.code === "custom" ? issue.params?.code : undefined;
+    return {
+        ok: false,
+        response: jsonError(400, issue?.message ?? "That request isn't valid.", typeof named === "string" ? named : undefined),
+    };
+};
+/** The largest id an osu! beatmap (or any 32-bit signed id) can have. */
+export const MAX_ID = 2_147_483_647;
+const isPositiveId = (id) => id >= 1 && id <= MAX_ID;
+/**
+ * @function parseIdList
+ * @param raw {string | null} a comma-separated query value, like `?ids=`
+ * @param options {ParseIdListOptions} the most ids and the per-id check
+ * @returns {number[] | null} 1 to `max` ids in the order sent, each 1 to 10 plain digits and
+ *          valid; null for anything else (an empty part, spaces, signs, hex, exponents, too many)
+ */
+export const parseIdList = (raw, { max, isValid = isPositiveId }) => {
+    // The longest valid id (10 digits) plus a comma; a longer value is refused unread.
+    if (raw === null || raw.length > max * 11)
+        return null;
+    const parts = raw.split(",");
+    if (parts.some((part) => !/^\d{1,10}$/.test(part)))
+        return null;
+    const ids = parts.map(Number);
+    return ids.length <= max && ids.every(isValid) ? ids : null;
+};

package/dist/server/budget.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file src/server/budget.ts
+ * @desc A shared call budget, like the osu! API's: a global fixed window across every instance
+ *       and, optionally, each subject's share, counted in the same documents as rate limits. The
+ *       share is counted first, and a subject past its share never touches the global counter,
+ *       so one caller can't spend the budget for everyone. gate() is the beforeCall a request
+ *       hands @haruhimemoe/osu: once it says no, it says no for the rest of that request, and a
+ *       counter it can't write counts as no. Moved from pools (src/lib/osu-budget.ts) and packs
+ *       (src/lib/osu/attributes.ts), which held the same functions around their own constants.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type CounterStore, type RateLimitRule } from "./counter.js";
+/** createBudget's options. */
+export type BudgetOptions = CounterStore & {
+    /** The budget every caller shares (osu!: 50 calls a minute). */
+    global: RateLimitRule;
+    /** The subject the global counter is kept under (default "global"). */
+    globalSubject?: string;
+    /** Each subject's share, when one is passed (osu!: 20 calls a minute per IP). */
+    perSubject?: RateLimitRule;
+};
+/** What createBudget returns. */
+export type Budget = {
+    /**
+     * Takes one call from the budget: true when it fits the subject's share (when a subject is
+     * given) and the global window. Throws when a counter can't be written.
+     */
+    take: (subject?: string, nowMs?: number) => Promise<boolean>;
+    /** A beforeCall: true while the budget allows, false from its first no (or failure) on. */
+    gate: (subject?: string, now?: () => number) => () => Promise<boolean>;
+};
+/**
+ * @function createBudget
+ * @param options {BudgetOptions} the counters' store, the global rule and the per-subject share
+ * @returns {Budget} take and gate over those counters
+ */
+export declare const createBudget: ({ global, globalSubject, perSubject, ...store }: BudgetOptions) => Budget;

package/dist/server/budget.js

@@ -0,0 +1,46 @@
+/**
+ * @file src/server/budget.ts
+ * @desc A shared call budget, like the osu! API's: a global fixed window across every instance
+ *       and, optionally, each subject's share, counted in the same documents as rate limits. The
+ *       share is counted first, and a subject past its share never touches the global counter,
+ *       so one caller can't spend the budget for everyone. gate() is the beforeCall a request
+ *       hands @haruhimemoe/osu: once it says no, it says no for the rest of that request, and a
+ *       counter it can't write counts as no. Moved from pools (src/lib/osu-budget.ts) and packs
+ *       (src/lib/osu/attributes.ts), which held the same functions around their own constants.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { bumpCounter } from "./counter.js";
+/**
+ * @function createBudget
+ * @param options {BudgetOptions} the counters' store, the global rule and the per-subject share
+ * @returns {Budget} take and gate over those counters
+ */
+export const createBudget = ({ global, globalSubject = "global", perSubject, ...store }) => {
+    const take = async (subject, nowMs = Date.now()) => {
+        if (subject !== undefined && perSubject) {
+            const used = await bumpCounter(store, perSubject, subject, nowMs, 1);
+            if (used > perSubject.limit)
+                return false;
+        }
+        return (await bumpCounter(store, global, globalSubject, nowMs, 1)) <= global.limit;
+    };
+    const gate = (subject, now = Date.now) => {
+        let refused = false;
+        return async () => {
+            if (refused)
+                return false;
+            try {
+                if (await take(subject, now()))
+                    return true;
+            }
+            catch (error) {
+                console.error(`[${global.scope}] budget: couldn't count`, error);
+            }
+            refused = true;
+            return false;
+        };
+    };
+    return { take, gate };
+};

package/dist/server/client-ip.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file src/server/client-ip.ts
+ * @desc The caller's IP as Vercel reports it (x-real-ip, then the first x-forwarded-for entry),
+ *       and the subject every per-IP counter keys on: an IPv4 address whole, an IPv6 address by
+ *       its /64, since one host usually gets a whole /64. Vercel's edge overwrites both headers
+ *       with the connecting client's IP (it never appends a client-sent value), so neither can be
+ *       spoofed in production. That holds only while Vercel is the first hop: behind another
+ *       proxy or CDN, both headers carry whatever that hop sends. Byte-identical in packs and
+ *       pools (src/utils/client-ip.ts) before it moved here.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** Longest IPv6 text is 45 characters; anything longer is junk, and it becomes part of an _id. */
+export declare const MAX_IP_LENGTH = 64;
+/**
+ * @function clientIp
+ * @param headers {Headers} request headers
+ * @returns {string} the IP, or "unknown" when neither header has one
+ */
+export declare const clientIp: (headers: Headers) => string;
+/**
+ * @function rateLimitSubject
+ * @param ip {string} what clientIp returned
+ * @returns {string} the counter subject: an IPv4 address unchanged; the IPv4 part of an
+ *          IPv4-mapped IPv6 address; any other IPv6 address as "g1:g2:g3:g4::/64" (lowercase, no
+ *          leading zeros), so every address in one /64 shares a counter; "unknown" and anything
+ *          that isn't an address unchanged
+ */
+export declare const rateLimitSubject: (ip: string) => string;

package/dist/server/client-ip.js

@@ -0,0 +1,92 @@
+/**
+ * @file src/server/client-ip.ts
+ * @desc The caller's IP as Vercel reports it (x-real-ip, then the first x-forwarded-for entry),
+ *       and the subject every per-IP counter keys on: an IPv4 address whole, an IPv6 address by
+ *       its /64, since one host usually gets a whole /64. Vercel's edge overwrites both headers
+ *       with the connecting client's IP (it never appends a client-sent value), so neither can be
+ *       spoofed in production. That holds only while Vercel is the first hop: behind another
+ *       proxy or CDN, both headers carry whatever that hop sends. Byte-identical in packs and
+ *       pools (src/utils/client-ip.ts) before it moved here.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** Longest IPv6 text is 45 characters; anything longer is junk, and it becomes part of an _id. */
+export const MAX_IP_LENGTH = 64;
+/**
+ * @function clientIp
+ * @param headers {Headers} request headers
+ * @returns {string} the IP, or "unknown" when neither header has one
+ */
+export const clientIp = (headers) => {
+    const real = headers.get("x-real-ip")?.trim();
+    const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+    return (real || forwarded || "unknown").slice(0, MAX_IP_LENGTH);
+};
+const HEX_GROUP = /^[0-9a-f]{1,4}$/;
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/**
+ * @function ipv4Groups
+ * @param text {string} a dotted IPv4 address
+ * @returns {number[] | null} its two 16-bit groups, or null when it isn't one
+ */
+const ipv4Groups = (text) => {
+    const octets = IPV4.exec(text)?.slice(1).map(Number);
+    if (!octets || octets.some((octet) => octet > 255))
+        return null;
+    const [a = 0, b = 0, c = 0, d = 0] = octets;
+    return [(a << 8) | b, (c << 8) | d];
+};
+/**
+ * @function ipv6Groups
+ * @param text {string} a lowercase IPv6 address, possibly compressed or ending in dotted IPv4
+ * @returns {number[] | null} its eight 16-bit groups, or null when it isn't one
+ */
+const ipv6Groups = (text) => {
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const parse = (half) => {
+        if (half === "")
+            return [];
+        const parts = half.split(":");
+        const groups = [];
+        for (const [index, part] of parts.entries()) {
+            if (HEX_GROUP.test(part))
+                groups.push(Number.parseInt(part, 16));
+            else if (index === parts.length - 1 && ipv4Groups(part))
+                groups.push(...(ipv4Groups(part) ?? []));
+            else
+                return null;
+        }
+        return groups;
+    };
+    const head = parse(halves[0] ?? "");
+    const tail = halves.length === 2 ? parse(halves[1] ?? "") : [];
+    if (!head || !tail)
+        return null;
+    if (halves.length === 1)
+        return head.length === 8 ? head : null;
+    const missing = 8 - head.length - tail.length;
+    return missing >= 1 ? [...head, ...Array(missing).fill(0), ...tail] : null;
+};
+/**
+ * @function rateLimitSubject
+ * @param ip {string} what clientIp returned
+ * @returns {string} the counter subject: an IPv4 address unchanged; the IPv4 part of an
+ *          IPv4-mapped IPv6 address; any other IPv6 address as "g1:g2:g3:g4::/64" (lowercase, no
+ *          leading zeros), so every address in one /64 shares a counter; "unknown" and anything
+ *          that isn't an address unchanged
+ */
+export const rateLimitSubject = (ip) => {
+    if (!ip.includes(":"))
+        return ip;
+    const groups = ipv6Groups(ip.toLowerCase());
+    if (!groups)
+        return ip;
+    const [g1 = 0, g2 = 0, g3 = 0, g4 = 0, g5 = 0, g6 = 0, g7 = 0, g8 = 0] = groups;
+    if (g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0 && g6 === 0xffff) {
+        return [g7 >> 8, g7 & 0xff, g8 >> 8, g8 & 0xff].join(".");
+    }
+    return `${[g1, g2, g3, g4].map((group) => group.toString(16)).join(":")}::/64`;
+};

package/dist/server/counter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file src/server/counter.ts
+ * @desc Fixed windows and the counter document rate limits and budgets share: one document per
+ *       scope, subject and window (`{scope}:{subject}:{windowStartSeconds}`), bumped with one
+ *       findOneAndUpdate upsert $inc, removed by the TTL index on expiresAt a minute after its
+ *       window ends. Before, each app computed the window three times (rate limits and two osu!
+ *       budget windows). counterTtlIndex is the index that removes them.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { Collection, Db } from "mongodb";
+import { type IndexSpec } from "../mongo/indexes.js";
+/** A fixed-window limit: at most `limit` hits per `windowSeconds`, counted under `scope`. */
+export type RateLimitRule = {
+    scope: string;
+    limit: number;
+    windowSeconds: number;
+};
+/** The collection both apps keep counters in. */
+export declare const RATE_LIMITS_COLLECTION = "rate_limits";
+/** MongoDB's TTL monitor runs about once a minute; the grace keeps a live window's counter. */
+export declare const COUNTER_GRACE_MS = 60000;
+/**
+ * @function counterTtlIndex
+ * @param collection {string} the counters' collection (default RATE_LIMITS_COLLECTION)
+ * @returns {IndexSpec} the TTL index on expiresAt that removes spent counters (pass it to
+ *          ensureIndexes from @haruhimemoe/next-kit/mongo)
+ */
+export declare const counterTtlIndex: (collection?: string) => IndexSpec;
+/** One counter document. */
+export type CounterDoc = {
+    _id: string;
+    count: number;
+    expiresAt: Date;
+};
+/** Where a counter lives: the database (resolved per call) and the collection name. */
+export type CounterStore = {
+    db: () => Promise<Db>;
+    collection?: string;
+};
+/** The window holding a moment, and when its counter may be removed. */
+export type RateLimitWindow = {
+    start: number;
+    end: number;
+    resetSeconds: number;
+    expiresAt: Date;
+};
+/**
+ * @function windowFor
+ * @param rule {RateLimitRule} the limit
+ * @param nowMs {number} current time (ms)
+ * @returns {RateLimitWindow} the window holding nowMs; resetSeconds is 1 to windowSeconds
+ */
+export declare const windowFor: (rule: RateLimitRule, nowMs: number) => RateLimitWindow;
+/**
+ * @function rateLimitId
+ * @param rule {RateLimitRule} the limit
+ * @param subject {string} an IP subject, a user subject or a fixed one like "global"
+ * @param nowMs {number} current time (ms)
+ * @returns {string} "{scope}:{subject}:{windowStartSeconds}"
+ */
+export declare const rateLimitId: (rule: RateLimitRule, subject: string, nowMs: number) => string;
+/**
+ * @function counters
+ * @param store {CounterStore} database and collection
+ * @returns {Promise<Collection<CounterDoc>>} the counter collection
+ */
+export declare const counters: ({ db, collection, }: CounterStore) => Promise<Collection<CounterDoc>>;
+/**
+ * @function bumpCounter
+ * @param store {CounterStore} database and collection
+ * @param rule {RateLimitRule} the limit
+ * @param subject {string} who is counted
+ * @param nowMs {number} current time (ms)
+ * @param cost {number} how much to add
+ * @returns {Promise<number>} the count after this bump
+ * @throws when the counter can't be written
+ */
+export declare const bumpCounter: (store: CounterStore, rule: RateLimitRule, subject: string, nowMs: number, cost: number) => Promise<number>;