@ttt-productions/rate-limit-core 0.2.0

package/dist/error-message.d.ts

@@ -0,0 +1,23 @@
+export interface RateLimitErrorMessageOptions {
+    /** Epoch ms when the limit resets (returned by `checkRateLimit`). */
+    reset: number;
+    /** Optional context shown in the message (e.g. "Upload"). */
+    context?: string;
+    /** Optional copy overrides — generic defaults are used when omitted. */
+    copy?: {
+        /** Suffix appended to every message. Default: "" (none). */
+        suffix?: string;
+        /** Template builder. Receives the formatted time string and context. */
+        format?: (args: {
+            timeString: string;
+            context?: string;
+        }) => string;
+    };
+}
+/**
+ * Generate a user-friendly rate-limit error message with relative time.
+ * Copy is fully consumer-controlled — TTT supplies its "Early-launch
+ * rate limits in place" suffix at the call site.
+ */
+export declare function getRateLimitErrorMessage(opts: RateLimitErrorMessageOptions): string;
+//# sourceMappingURL=error-message.d.ts.map

package/dist/error-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-message.d.ts","sourceRoot":"","sources":["../src/error-message.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,IAAI,CAAC,EAAE;QACL,4DAA4D;QAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,wEAAwE;QACxE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,KAAK,MAAM,CAAC;KACrE,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,4BAA4B,GAAG,MAAM,CAcnF"}

package/dist/error-message.js

@@ -0,0 +1,18 @@
+/**
+ * Generate a user-friendly rate-limit error message with relative time.
+ * Copy is fully consumer-controlled — TTT supplies its "Early-launch
+ * rate limits in place" suffix at the call site.
+ */
+export function getRateLimitErrorMessage(opts) {
+    const { reset, context, copy } = opts;
+    const minutes = Math.max(1, Math.ceil((reset - Date.now()) / 60_000));
+    const timeString = minutes === 1 ? "1 minute" : `${minutes} minutes`;
+    if (copy?.format) {
+        return copy.format({ timeString, context });
+    }
+    const base = context
+        ? `${context} rate limit exceeded. Try again in ${timeString}.`
+        : `Rate limit exceeded. Try again in ${timeString}.`;
+    return copy?.suffix ? `${base} ${copy.suffix}` : base;
+}
+//# sourceMappingURL=error-message.js.map

package/dist/error-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-message.js","sourceRoot":"","sources":["../src/error-message.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAkC;IACzE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,UAAU,CAAC;IAErE,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,OAAO;QAClB,CAAC,CAAC,GAAG,OAAO,sCAAsC,UAAU,GAAG;QAC/D,CAAC,CAAC,qCAAqC,UAAU,GAAG,CAAC;IAEvD,OAAO,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createRedisClientFactory } from "./redis-client.js";
+export type { RedisCredentialsProvider, RedisClientFactoryOptions, } from "./redis-client.js";
+export { createRateLimiterFactory } from "./rate-limiter.js";
+export type { RateLimitConfig, RateLimiterFactoryOptions, } from "./rate-limiter.js";
+export { getRateLimitErrorMessage } from "./error-message.js";
+export type { RateLimitErrorMessageOptions } from "./error-message.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EACV,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EACV,eAAe,EACf,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createRedisClientFactory } from "./redis-client.js";
+export { createRateLimiterFactory } from "./rate-limiter.js";
+export { getRateLimitErrorMessage } from "./error-message.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAM7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAM7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,30 @@
+import { Ratelimit } from "@upstash/ratelimit";
+import type { Redis } from "@upstash/redis";
+export interface RateLimitConfig {
+    /** Unique prefix for this limiter (e.g. "ratelimit:upload"). */
+    prefix: string;
+    /** Max requests allowed in the window. */
+    maxRequests: number;
+    /** Window duration (e.g. "1 h", "10 m", "1 d"). */
+    window: string;
+}
+export interface RateLimiterFactoryOptions {
+    /** Returns the Redis client or null when disabled. */
+    getRedis: () => Redis | null;
+    /** When true, includes Upstash analytics. Default true. */
+    analytics?: boolean;
+}
+/**
+ * Create a memoized Ratelimit factory. Limiters are cached by their `prefix`
+ * so repeated calls with the same config return the same instance.
+ */
+export declare function createRateLimiterFactory(options: RateLimiterFactoryOptions): {
+    getRateLimiter: (config: RateLimitConfig) => Ratelimit | null;
+    checkRateLimit: (key: string, config: RateLimitConfig) => Promise<{
+        allowed: true;
+    } | {
+        allowed: false;
+        reset: number;
+    }>;
+};
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,KAAK,GAAG,IAAI,CAAC;IAC7B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB;6BAIzC,eAAe,KAAG,SAAS,GAAG,IAAI;0BAsB3D,MAAM,UACH,eAAe,KACtB,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;EASlE"}

package/dist/rate-limiter.js

@@ -0,0 +1,40 @@
+import { Ratelimit } from "@upstash/ratelimit";
+/**
+ * Create a memoized Ratelimit factory. Limiters are cached by their `prefix`
+ * so repeated calls with the same config return the same instance.
+ */
+export function createRateLimiterFactory(options) {
+    const limiters = new Map();
+    const analytics = options.analytics ?? true;
+    function getRateLimiter(config) {
+        const redis = options.getRedis();
+        if (!redis)
+            return null;
+        const existing = limiters.get(config.prefix);
+        if (existing)
+            return existing;
+        const limiter = new Ratelimit({
+            redis,
+            limiter: Ratelimit.slidingWindow(config.maxRequests, config.window),
+            analytics,
+            prefix: config.prefix,
+        });
+        limiters.set(config.prefix, limiter);
+        return limiter;
+    }
+    /**
+     * Check rate limit for a key (e.g. userId). Returns `{ allowed: true }`
+     * when Redis is disabled OR the limit isn't exceeded.
+     */
+    async function checkRateLimit(key, config) {
+        const limiter = getRateLimiter(config);
+        if (!limiter)
+            return { allowed: true };
+        const { success, reset } = await limiter.limit(key);
+        if (!success)
+            return { allowed: false, reset };
+        return { allowed: true };
+    }
+    return { getRateLimiter, checkRateLimit };
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAmB/C;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAE5C,SAAS,cAAc,CAAC,MAAuB;QAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,OAAO,GAAG,IAAI,SAAS,CAAC;YAC5B,KAAK;YACL,OAAO,EAAE,SAAS,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAuD,CAAC;YACpH,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QACH,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,KAAK,UAAU,cAAc,CAC3B,GAAW,EACX,MAAuB;QAEvB,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACvC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC5C,CAAC"}

package/dist/redis-client.d.ts

@@ -0,0 +1,28 @@
+import { Redis } from "@upstash/redis";
+export interface RedisCredentialsProvider {
+    /** Lazy URL resolver — invoked only when Redis is first needed. */
+    url: () => string | undefined;
+    /** Lazy token resolver — invoked only when Redis is first needed. */
+    token: () => string | undefined;
+}
+export interface RedisClientFactoryOptions {
+    credentials: RedisCredentialsProvider;
+    /** Optional disable hook (e.g. emulator/local-dev detection). When this returns true on first call, Redis is permanently disabled for this factory instance. */
+    disabledWhen?: () => boolean;
+    /** Optional logger for "Redis not configured" / "disabled" diagnostics. */
+    logger?: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+    };
+}
+/**
+ * Build a lazy, singleton Redis client. The client is constructed on first
+ * `get()` and reused thereafter. Returns null when credentials are missing
+ * or the disable hook returned true at first access.
+ */
+export declare function createRedisClientFactory(options: RedisClientFactoryOptions): {
+    get(): Redis | null;
+    /** Test-only: reset cached state. Do not call in production. */
+    __reset(): void;
+};
+//# sourceMappingURL=redis-client.d.ts.map

package/dist/redis-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-client.d.ts","sourceRoot":"","sources":["../src/redis-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,GAAG,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC9B,qEAAqE;IACrE,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,wBAAwB,CAAC;IACtC,gKAAgK;IAChK,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IAC7B,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KAClC,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG;IAC5E,GAAG,IAAI,KAAK,GAAG,IAAI,CAAC;IACpB,gEAAgE;IAChE,OAAO,IAAI,IAAI,CAAC;CACjB,CAoCA"}

package/dist/redis-client.js

@@ -0,0 +1,43 @@
+import { Redis } from "@upstash/redis";
+/**
+ * Build a lazy, singleton Redis client. The client is constructed on first
+ * `get()` and reused thereafter. Returns null when credentials are missing
+ * or the disable hook returned true at first access.
+ */
+export function createRedisClientFactory(options) {
+    let cached = null;
+    let disabled = false;
+    let resolved = false;
+    function resolve() {
+        if (resolved)
+            return cached;
+        resolved = true;
+        if (options.disabledWhen?.()) {
+            options.logger?.info?.("[rate-limit-core] Redis disabled by disabledWhen hook.");
+            disabled = true;
+            return null;
+        }
+        const url = options.credentials.url();
+        const token = options.credentials.token();
+        if (!url || !token) {
+            options.logger?.warn?.("[rate-limit-core] Redis credentials not configured.");
+            disabled = true;
+            return null;
+        }
+        cached = new Redis({ url, token });
+        return cached;
+    }
+    return {
+        get() {
+            if (disabled)
+                return null;
+            return resolve();
+        },
+        __reset() {
+            cached = null;
+            disabled = false;
+            resolved = false;
+        },
+    };
+}
+//# sourceMappingURL=redis-client.js.map

package/dist/redis-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-client.js","sourceRoot":"","sources":["../src/redis-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAoBvC;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IAKzE,IAAI,MAAM,GAAiB,IAAI,CAAC;IAChC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,SAAS,OAAO;QACd,IAAI,QAAQ;YAAE,OAAO,MAAM,CAAC;QAC5B,QAAQ,GAAG,IAAI,CAAC;QAEhB,IAAI,OAAO,CAAC,YAAY,EAAE,EAAE,EAAE,CAAC;YAC7B,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,wDAAwD,CAAC,CAAC;YACjF,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QAC1C,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,qDAAqD,CAAC,CAAC;YAC9E,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,IAAI,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QACnC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO;QACL,GAAG;YACD,IAAI,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC1B,OAAO,OAAO,EAAE,CAAC;QACnB,CAAC;QACD,OAAO;YACL,MAAM,GAAG,IAAI,CAAC;YACd,QAAQ,GAAG,KAAK,CAAC;YACjB,QAAQ,GAAG,KAAK,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@ttt-productions/rate-limit-core",
+    "version": "0.2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ttt-productions/ttt-packages.git",
+        "directory": "packages/rate-limit-core"
+    },
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "sideEffects": false,
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist *.tsbuildinfo",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "peerDependencies": {
+        "@upstash/ratelimit": ">=2.0.0",
+        "@upstash/redis": ">=1.34.0"
+    },
+    "devDependencies": {
+        "@upstash/ratelimit": "^2.0.0",
+        "@upstash/redis": "^1.34.0",
+        "typescript": "^5.8.3"
+    },
+    "engines": {
+        "node": ">=22",
+        "npm": ">=10"
+    },
+    "author": "DJ (TTT Productions)",
+    "license": "MIT"
+}