@ysk-kit/api-http 1.0.1 → 1.1.0

package/README.md

@@ -0,0 +1,7 @@
+# @ysk-kit/api-http
+
+Framework-free HTTP handlers, OpenAPI, and rate limits for YSK Kit.
+
+- Homepage: https://ysk.hk/products/ysk-kit
+- Source: https://github.com/yanshekki/ysk-kit/tree/main/packages/api-http
+- License: MIT

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { type EnvelopeErrorJson, envelopeError } from './envelope-error';
 export { type ContractRoute, type ContractRouter, flattenContract, type HttpMethod, } from './flatten';
 export { buildOpenApiDocument, type OpenApiDocument, scalarDocsHtml, } from './openapi';
-export { clientIp, createMemoryRateLimit, isRateLimitSkipped, type RateLimitOpts, } from './rate-limit';
+export { clientIp, createMemoryRateLimit, createRateLimit, createRedisRateLimit, isRateLimitSkipped, type RateLimiter, type RateLimitOpts, type RateLimitRedis, } from './rate-limit';
 export { REQUEST_ID_HEADER } from './request-id';
 export { applySecurityHeaders, securityHeaders } from './security-headers';
 export { type HttpCtx, type HttpHandler, type HttpResult, headerValue } from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,eAAe,EACf,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,eAAe,EACf,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 export { envelopeError } from './envelope-error';
 export { flattenContract, } from './flatten';
 export { buildOpenApiDocument, scalarDocsHtml, } from './openapi';
-export { clientIp, createMemoryRateLimit, isRateLimitSkipped, } from './rate-limit';
+export { clientIp, createMemoryRateLimit, createRateLimit, createRedisRateLimit, isRateLimitSkipped, } from './rate-limit';
 export { REQUEST_ID_HEADER } from './request-id';
 export { applySecurityHeaders, securityHeaders } from './security-headers';
 export { headerValue } from './types';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAGL,eAAe,GAEhB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,oBAAoB,EAEpB,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,kBAAkB,GAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAmD,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAGL,eAAe,GAEhB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,oBAAoB,EAEpB,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,GAInB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAmD,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/rate-limit.d.ts

@@ -5,7 +5,22 @@ export type RateLimitOpts = {
 };
 export declare const clientIp: (forwarded: string | string[] | undefined, remote: string | undefined) => string;
 export declare const isRateLimitSkipped: (path: string) => boolean;
-export declare const createMemoryRateLimit: (opts: RateLimitOpts) => {
-    check(ip: string, path: string): void;
+/** Minimal Redis surface so the HTTP package does not import ioredis. */
+export type RateLimitRedis = {
+    incr(key: string): Promise<number>;
+    pexpire(key: string, milliseconds: number): Promise<unknown>;
 };
+export type RateLimiter = {
+    check(ip: string, path: string): void | Promise<void>;
+};
+export declare const createMemoryRateLimit: (opts: RateLimitOpts) => RateLimiter;
+/** Fixed window shared across API processes. Used when `REDIS_URL` is set. */
+export declare const createRedisRateLimit: (opts: RateLimitOpts & {
+    redis: RateLimitRedis;
+    now?: () => number;
+    prefix?: string;
+}) => RateLimiter;
+export declare const createRateLimit: (opts: RateLimitOpts & {
+    redis?: RateLimitRedis;
+}) => RateLimiter;
 //# sourceMappingURL=rate-limit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC,CAAC;AAEF,eAAO,MAAM,QAAQ,GACnB,WAAW,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EACxC,QAAQ,MAAM,GAAG,SAAS,KACzB,MAKF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OACc,CAAC;AAEjE,eAAO,MAAM,qBAAqB,GAAI,MAAM,aAAa;cAK3C,MAAM,QAAQ,MAAM,GAAG,IAAI;CAaxC,CAAC"}
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC,CAAC;AAEF,eAAO,MAAM,QAAQ,GACnB,WAAW,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EACxC,QAAQ,MAAM,GAAG,SAAS,KACzB,MAKF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OACc,CAAC;AAEjE,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,MAAM,aAAa,KAAG,WAkB3D,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,GAC/B,MAAM,aAAa,GAAG;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KACnF,WAcF,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,MAAM,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,cAAc,CAAA;CAAE,KAAG,WAUlF,CAAC"}

package/dist/rate-limit.js

@@ -26,4 +26,34 @@ export const createMemoryRateLimit = (opts) => {
         },
     };
 };
+/** Fixed window shared across API processes. Used when `REDIS_URL` is set. */
+export const createRedisRateLimit = (opts) => {
+    const skip = opts.skipPath ?? isRateLimitSkipped;
+    const prefix = opts.prefix ?? 'ysk-rl';
+    return {
+        async check(ip, path) {
+            if (skip(path))
+                return;
+            const now = (opts.now ?? Date.now)();
+            const bucket = Math.floor(now / opts.windowMs);
+            const key = `${prefix}:${ip}:${bucket}`;
+            const count = await opts.redis.incr(key);
+            if (count === 1)
+                await opts.redis.pexpire(key, opts.windowMs);
+            if (count > opts.max)
+                throw new AppError('RATE_LIMITED');
+        },
+    };
+};
+export const createRateLimit = (opts) => {
+    if (opts.redis) {
+        return createRedisRateLimit({
+            windowMs: opts.windowMs,
+            max: opts.max,
+            redis: opts.redis,
+            ...(opts.skipPath ? { skipPath: opts.skipPath } : {}),
+        });
+    }
+    return createMemoryRateLimit(opts);
+};
 //# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAQlD,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,SAAwC,EACxC,MAA0B,EAClB,EAAE;IACV,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,MAAM,KAAK,GAAG,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACzC,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,MAAM,IAAI,SAAS,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAY,EAAW,EAAE,CAC1D,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ,CAAC;AAEjE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,IAAmB,EAAE,EAAE;IAC3D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,kBAAkB,CAAC;IAEjD,OAAO;QACL,KAAK,CAAC,EAAU,EAAE,IAAY;YAC5B,IAAI,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO;YACvB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;YACxC,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC;YACrE,IAAI,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;gBACrB,MAAM,IAAI,QAAQ,CAAC,cAAc,CAAC,CAAC;YACrC,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ysk-kit/api-http",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,15 +11,15 @@
     }
   },
   "dependencies": {
-    "@ysk-kit/auth": "1.0.1",
-    "@ysk-kit/contracts": "1.0.1",
-    "@ysk-kit/domain-kernel": "1.0.1",
+    "@ysk-kit/auth": "1.1.0",
+    "@ysk-kit/contracts": "1.1.0",
+    "@ysk-kit/domain-kernel": "1.1.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^24.5.2",
+    "@types/node": "^24.19.0",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.3"
   },
   "files": [
     "dist"
@@ -28,6 +28,14 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
+  "license": "MIT",
+  "description": "Framework-free HTTP handlers, OpenAPI, and rate limits for YSK Kit.",
+  "homepage": "https://ysk.hk/products/ysk-kit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yanshekki/ysk-kit.git",
+    "directory": "packages/api-http"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --passWithNoTests",