@modularizer/plat-client 0.4.0

package/dist/server/core.js

@@ -0,0 +1,215 @@
+import { createToolDefinition } from './tools.js';
+import { generateRouteVariants } from './routing.js';
+import { ensureControllerMeta, ensureRouteMeta, getControllerMeta, pendingRoutes, ROUTE_METADATA_KEY } from '../spec/index.js';
+const RESERVED_METHOD_NAMES = ['tools', 'routes', 'endpoints', 'help', 'openapi'];
+export class PLATServerCore {
+    options;
+    stores;
+    constructor(options, stores) {
+        this.options = options;
+        this.stores = stores;
+    }
+    registerControllers(...ControllerClasses) {
+        const registered = [];
+        for (const ControllerClass of ControllerClasses) {
+            const meta = getControllerMeta(ControllerClass) ?? ensureControllerMeta(ControllerClass);
+            if (!meta.basePath)
+                meta.basePath = ControllerClass.name;
+            if (!meta.tag)
+                meta.tag = meta.basePath || ControllerClass.name;
+            const instance = new ControllerClass();
+            const controllerTag = meta.tag || meta.basePath || ControllerClass.name;
+            const lowerControllerTag = controllerTag.toLowerCase();
+            if (RESERVED_METHOD_NAMES.includes(lowerControllerTag)) {
+                throw new Error(`Controller '${controllerTag}' uses a reserved plat system name. ` +
+                    `Reserved names: ${RESERVED_METHOD_NAMES.join(', ')}. ` +
+                    `Choose a different controller name/tag.`);
+            }
+            if (this.stores.registeredMethodNames.has(controllerTag)) {
+                throw new Error(`Controller '${controllerTag}' conflicts with an existing method name. ` +
+                    `Controller names and method names must not overlap. ` +
+                    `Rename either the controller or the method.`);
+            }
+            this.stores.registeredControllerNames.add(controllerTag);
+            this.processPendingRoutes(ControllerClass);
+            const freshMeta = getControllerMeta(ControllerClass);
+            const routes = this.collectRoutes(ControllerClass, freshMeta);
+            for (const [key, route] of routes.entries()) {
+                const methodName = String(key);
+                this.validateMethodName(methodName, ControllerClass.name);
+                if (this.stores.registeredControllerNames.has(methodName)) {
+                    throw new Error(`Method '${methodName}' in ${ControllerClass.name} conflicts with controller name '${methodName}'. ` +
+                        `Method names and controller names must not overlap. ` +
+                        `Rename either the method or the controller.`);
+                }
+                if (this.stores.registeredMethodNames.has(methodName)) {
+                    throw new Error(`Duplicate operationId: method "${methodName}" is defined in multiple controllers. ` +
+                        `In plat, method names must be globally unique across all controllers. ` +
+                        `Consider renaming one of these methods to have a unique name. ` +
+                        `Current controller: ${ControllerClass.name}`);
+                }
+                this.stores.registeredMethodNames.add(methodName);
+                const fullPath = '/' + methodName;
+                const routeMeta = freshMeta?.routes.get(key);
+                this.stores.tools.set(methodName, createToolDefinition({
+                    name: methodName,
+                    summary: routeMeta?.summary ?? routeMeta?.opts?.summary,
+                    description: routeMeta?.description ?? routeMeta?.opts?.description ?? `${route.method.toUpperCase()} ${fullPath}`,
+                    method: route.method,
+                    path: fullPath,
+                    controller: controllerTag,
+                    tags: [
+                        controllerTag,
+                        ...(Array.isArray(routeMeta?.opts?.tags) ? routeMeta?.opts?.tags : []),
+                    ].filter((value, index, arr) => Boolean(value) && arr.indexOf(value) === index),
+                    examples: Array.isArray(routeMeta?.opts?.examples) ? routeMeta?.opts?.examples : undefined,
+                    hidden: routeMeta?.opts?.hidden === true,
+                    safe: routeMeta?.opts?.safe ?? ['GET', 'HEAD'].includes(route.method.toUpperCase()),
+                    idempotent: routeMeta?.opts?.idempotent ?? ['GET', 'HEAD', 'PUT', 'DELETE'].includes(route.method.toUpperCase()),
+                    longRunning: routeMeta?.opts?.longRunning === true,
+                    input_schema: routeMeta?.inputSchema ? createToolDefinition(methodName, route.method, fullPath, '', routeMeta.inputSchema).input_schema : undefined,
+                    response_schema: routeMeta?.outputSchema ? createToolDefinition(methodName, route.method, fullPath, '', undefined, routeMeta.outputSchema).response_schema : undefined,
+                }));
+                const operation = {
+                    method: route.method.toUpperCase(),
+                    path: fullPath,
+                    methodName,
+                    boundMethod: instance[methodName].bind(instance),
+                    controllerTag,
+                    routeMeta,
+                    controllerMeta: freshMeta,
+                };
+                this.stores.operationRegistry.register(operation);
+                const routeRecord = {
+                    method: route.method.toUpperCase(),
+                    path: fullPath,
+                    methodName,
+                };
+                this.stores.routes.push(routeRecord);
+                registered.push({
+                    operation,
+                    route: routeRecord,
+                    variants: generateRouteVariants(methodName, route.method)
+                        .filter((variant) => !(variant.path === fullPath && variant.method === route.method.toUpperCase())),
+                });
+            }
+        }
+        return registered;
+    }
+    processPendingRoutes(ControllerClass) {
+        if (!pendingRoutes.has(ControllerClass))
+            return;
+        const routes = pendingRoutes.get(ControllerClass);
+        for (const route of routes) {
+            const routeMeta = ensureRouteMeta(ControllerClass, route.key);
+            routeMeta.method = route.method;
+            routeMeta.path = '/' + String(route.key);
+            routeMeta.auth = route.opts?.auth;
+            routeMeta.rateLimit = route.opts?.rateLimit;
+            routeMeta.tokenLimit = route.opts?.tokenLimit;
+            routeMeta.cache = route.opts?.cache;
+            routeMeta.summary = route.opts?.summary;
+            routeMeta.description = route.opts?.description;
+            if (route.opts) {
+                routeMeta.opts = route.opts;
+            }
+        }
+        pendingRoutes.delete(ControllerClass);
+    }
+    collectRoutes(ControllerClass, freshMeta) {
+        const routes = new Map();
+        const undecoratedMode = this.options.undecoratedMode ?? 'POST';
+        for (const key of Object.getOwnPropertyNames(ControllerClass.prototype)) {
+            if (key === 'constructor')
+                continue;
+            if (key.startsWith('_'))
+                continue;
+            const method = ControllerClass.prototype[key];
+            if (typeof method !== 'function')
+                continue;
+            const routeData = method[ROUTE_METADATA_KEY];
+            if (routeData) {
+                routes.set(key, { method: routeData.httpMethod });
+            }
+            else if (undecoratedMode !== 'private') {
+                routes.set(key, { method: undecoratedMode });
+            }
+        }
+        if (freshMeta) {
+            for (const [key, routeMeta] of freshMeta.routes.entries()) {
+                const keyName = String(key);
+                const prototypeMethod = ControllerClass.prototype?.[keyName];
+                if (typeof prototypeMethod !== 'function' || keyName === 'constructor' || keyName.startsWith('_')) {
+                    continue;
+                }
+                const inferredMethod = routeMeta.method ?? (undecoratedMode !== 'private' ? undecoratedMode : undefined);
+                if (!inferredMethod)
+                    continue;
+                routes.set(key, { method: inferredMethod });
+                if (this.options.validateRouteOpts && routeMeta.opts) {
+                    const result = this.options.validateRouteOpts(routeMeta.opts, String(key), routeMeta.path);
+                    if (result && typeof result === 'object' && 'then' in result) {
+                        // Keep behavior aligned with the current server host.
+                    }
+                }
+            }
+        }
+        return routes;
+    }
+    extractMethodPrefix(methodName) {
+        const standardPrefixes = ['create', 'update', 'delete', 'list', 'find', 'send', 'get', 'do'];
+        for (const prefix of standardPrefixes) {
+            if (methodName.startsWith(prefix) && methodName.length > prefix.length) {
+                const nextChar = methodName.charAt(prefix.length);
+                if (nextChar === nextChar.toUpperCase()) {
+                    return prefix;
+                }
+            }
+        }
+        for (let i = 1; i < methodName.length; i++) {
+            const char = methodName.charAt(i);
+            if (char === char.toUpperCase() && char !== char.toLowerCase()) {
+                return methodName.substring(0, i);
+            }
+        }
+        return methodName.length > 0 ? methodName : null;
+    }
+    validateMethodName(methodName, controllerName) {
+        if (!methodName || methodName.length === 0)
+            return;
+        const firstChar = methodName.charAt(0);
+        if (firstChar === firstChar.toUpperCase() && firstChar !== firstChar.toLowerCase()) {
+            throw new Error(`Method '${methodName}' in ${controllerName} violates plat naming convention: ` +
+                `method names must start with a lowercase letter. ` +
+                `Use '${firstChar.toLowerCase()}${methodName.slice(1)}' instead.`);
+        }
+        if (methodName.includes('_')) {
+            const camelCase = methodName.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
+            throw new Error(`Method '${methodName}' in ${controllerName} violates plat naming convention: ` +
+                `underscores are not allowed. Use camelCase instead. ` +
+                `Use '${camelCase}' instead.`);
+        }
+        if (RESERVED_METHOD_NAMES.includes(methodName.toLowerCase())) {
+            throw new Error(`Method '${methodName}' in ${controllerName} uses a reserved plat system name. ` +
+                `Reserved names: ${RESERVED_METHOD_NAMES.join(', ')}. ` +
+                `Choose a different method name.`);
+        }
+        if (this.options.allowedMethodPrefixes && this.options.allowedMethodPrefixes !== '*') {
+            const prefix = this.extractMethodPrefix(methodName);
+            if (prefix && !this.options.allowedMethodPrefixes.includes(prefix)) {
+                throw new Error(`Method '${methodName}' in ${controllerName} uses disallowed prefix '${prefix}'. ` +
+                    `Allowed prefixes: ${this.options.allowedMethodPrefixes.join(', ')}. ` +
+                    `Rename the method to use an allowed prefix.`);
+            }
+        }
+        if (this.options.disAllowedMethodPrefixes && this.options.disAllowedMethodPrefixes.length > 0) {
+            const prefix = this.extractMethodPrefix(methodName);
+            if (prefix && this.options.disAllowedMethodPrefixes.includes(prefix)) {
+                throw new Error(`Method '${methodName}' in ${controllerName} uses disallowed prefix '${prefix}'. ` +
+                    `Disallowed prefixes: ${this.options.disAllowedMethodPrefixes.join(', ')}. ` +
+                    `Rename the method to use a different prefix.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=core.js.map

package/dist/server/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../typescript/src/server/core.ts"],"names":[],"mappings":"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"}

package/dist/server/operation-registry.d.ts

@@ -0,0 +1,9 @@
+import type { PLATServerCallEnvelope, PLATServerResolvedOperation } from './transports';
+export declare class PLATOperationRegistry {
+    private operationsById;
+    private operationsByRoute;
+    register(operation: PLATServerResolvedOperation): void;
+    resolve(envelope: Pick<PLATServerCallEnvelope, 'operationId' | 'method' | 'path'>): PLATServerResolvedOperation | undefined;
+    list(): PLATServerResolvedOperation[];
+}
+//# sourceMappingURL=operation-registry.d.ts.map

package/dist/server/operation-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-registry.d.ts","sourceRoot":"","sources":["../../../typescript/src/server/operation-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAA;AAEvF,qBAAa,qBAAqB;IAChC,OAAO,CAAC,cAAc,CAAiD;IACvE,OAAO,CAAC,iBAAiB,CAAiD;IAE1E,QAAQ,CAAC,SAAS,EAAE,2BAA2B,GAAG,IAAI;IAKtD,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,2BAA2B,GAAG,SAAS;IAK3H,IAAI,IAAI,2BAA2B,EAAE;CAGtC"}

package/dist/server/operation-registry.js

@@ -0,0 +1,16 @@
+export class PLATOperationRegistry {
+    operationsById = new Map();
+    operationsByRoute = new Map();
+    register(operation) {
+        this.operationsById.set(operation.methodName, operation);
+        this.operationsByRoute.set(`${operation.method.toUpperCase()} ${operation.path}`, operation);
+    }
+    resolve(envelope) {
+        return (envelope.operationId ? this.operationsById.get(envelope.operationId) : undefined)
+            ?? this.operationsByRoute.get(`${envelope.method.toUpperCase()} ${envelope.path}`);
+    }
+    list() {
+        return Array.from(this.operationsById.values());
+    }
+}
+//# sourceMappingURL=operation-registry.js.map

package/dist/server/operation-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-registry.js","sourceRoot":"","sources":["../../../typescript/src/server/operation-registry.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,qBAAqB;IACxB,cAAc,GAAG,IAAI,GAAG,EAAuC,CAAA;IAC/D,iBAAiB,GAAG,IAAI,GAAG,EAAuC,CAAA;IAE1E,QAAQ,CAAC,SAAsC;QAC7C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;QACxD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,CAAA;IAC9F,CAAC;IAED,OAAO,CAAC,QAAyE;QAC/E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;eACpF,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IACtF,CAAC;IAED,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAA;IACjD,CAAC;CACF"}

package/dist/server/param-aliases.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Parameter Aliasing
+ *
+ * Maps common parameter name variants to canonical plat parameter names.
+ * This ensures consistency while being resilient to common naming mistakes.
+ *
+ * Examples:
+ * - `query` → `q`
+ * - `search` → `q`
+ * - `format` → `fmt`
+ * - `page` + `pageSize` → `limit` + `offset`
+ */
+export interface ParameterAliases {
+    [alias: string]: string | ((value: any, params: Record<string, any>) => void);
+}
+/**
+ * Normalize/alias a parameters object
+ * Converts common parameter name variants to plat canonical names
+ *
+ * @param params The input parameters object
+ * @param paramCoercions Optional config map of parameter aliases (from PLATServerOptions)
+ * @param disAllowedParams Optional list of forbidden parameter names
+ * @returns New params object with aliased names resolved
+ * @throws Error if a disallowed parameter is found in the input
+ */
+export declare function normalizeParameters(params: Record<string, any>, paramCoercions?: Record<string, string>, disAllowedParams?: string[]): Record<string, any>;
+/**
+ * Get all known parameter aliases
+ * Useful for documentation and validation
+ */
+export declare function getKnownAliases(): Record<string, string>;
+/**
+ * Check if a parameter name would be aliased
+ */
+export declare function isAliasedParameter(paramName: string): boolean;
+/**
+ * Get canonical name for a parameter
+ */
+export declare function getCanonicalName(paramName: string): string | null;
+//# sourceMappingURL=param-aliases.d.ts.map

package/dist/server/param-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-aliases.d.ts","sourceRoot":"","sources":["../../../typescript/src/server/param-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC,CAAA;CAC9E;AAeD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAC1B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiDrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUjE"}

package/dist/server/param-aliases.js

@@ -0,0 +1,112 @@
+/**
+ * Parameter Aliasing
+ *
+ * Maps common parameter name variants to canonical plat parameter names.
+ * This ensures consistency while being resilient to common naming mistakes.
+ *
+ * Examples:
+ * - `query` → `q`
+ * - `search` → `q`
+ * - `format` → `fmt`
+ * - `page` + `pageSize` → `limit` + `offset`
+ */
+/**
+ * Map of parameter aliases to canonical names
+ * Value can be:
+ * - string: direct alias (query → q)
+ * - function: complex transformation (page/pageSize → limit/offset)
+ */
+const PARAMETER_ALIASES = {
+    query: 'q',
+    search: 'q',
+    format: 'fmt',
+    // Complex transformations are handled separately
+};
+/**
+ * Normalize/alias a parameters object
+ * Converts common parameter name variants to plat canonical names
+ *
+ * @param params The input parameters object
+ * @param paramCoercions Optional config map of parameter aliases (from PLATServerOptions)
+ * @param disAllowedParams Optional list of forbidden parameter names
+ * @returns New params object with aliased names resolved
+ * @throws Error if a disallowed parameter is found in the input
+ */
+export function normalizeParameters(params, paramCoercions, disAllowedParams) {
+    if (!params || typeof params !== 'object') {
+        return params;
+    }
+    // Check for disallowed parameters first
+    if (disAllowedParams && disAllowedParams.length > 0) {
+        for (const paramName of Object.keys(params)) {
+            if (disAllowedParams.includes(paramName)) {
+                throw new Error(`Parameter '${paramName}' is disallowed in this API. ` +
+                    `Use '${getCanonicalName(paramName) || 'a different parameter'}' instead.`);
+            }
+        }
+    }
+    const normalized = { ...params };
+    const aliases = paramCoercions || PARAMETER_ALIASES;
+    // Apply simple aliases
+    for (const [alias, canonical] of Object.entries(aliases)) {
+        if (typeof canonical === 'string' && alias in normalized && canonical) {
+            if (!(canonical in normalized)) {
+                normalized[canonical] = normalized[alias];
+            }
+            delete normalized[alias];
+        }
+    }
+    // Handle page/pageSize → limit/offset conversion
+    if ('page' in normalized || 'pageSize' in normalized) {
+        const page = normalized.page ?? 1;
+        const pageSize = normalized.pageSize ?? 10;
+        // Only apply if limit/offset aren't already set
+        if (!('limit' in normalized)) {
+            normalized.limit = pageSize;
+        }
+        if (!('offset' in normalized)) {
+            normalized.offset = (page - 1) * pageSize;
+        }
+        // Remove the original page/pageSize
+        delete normalized.page;
+        delete normalized.pageSize;
+    }
+    return normalized;
+}
+/**
+ * Get all known parameter aliases
+ * Useful for documentation and validation
+ */
+export function getKnownAliases() {
+    const aliases = {};
+    for (const [alias, canonical] of Object.entries(PARAMETER_ALIASES)) {
+        if (typeof canonical === 'string') {
+            aliases[alias] = canonical;
+        }
+    }
+    // Add page/pageSize special handling
+    aliases['page'] = 'offset (calculated as (page-1)*pageSize)';
+    aliases['pageSize'] = 'limit';
+    return aliases;
+}
+/**
+ * Check if a parameter name would be aliased
+ */
+export function isAliasedParameter(paramName) {
+    return paramName in PARAMETER_ALIASES || paramName === 'page' || paramName === 'pageSize';
+}
+/**
+ * Get canonical name for a parameter
+ */
+export function getCanonicalName(paramName) {
+    if (paramName === 'page')
+        return 'offset';
+    if (paramName === 'pageSize')
+        return 'limit';
+    const alias = PARAMETER_ALIASES[paramName];
+    if (typeof alias === 'string') {
+        return alias;
+    }
+    return null;
+}
+//# sourceMappingURL=param-aliases.js.map

package/dist/server/param-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-aliases.js","sourceRoot":"","sources":["../../../typescript/src/server/param-aliases.ts"],"names":[],"mappings":"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"}

package/dist/server/rate-limit/index.d.ts

@@ -0,0 +1,2 @@
+export * from './utils';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../typescript/src/server/rate-limit/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA"}

package/dist/server/rate-limit/index.js

@@ -0,0 +1,2 @@
+export * from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/server/rate-limit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../typescript/src/server/rate-limit/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA"}

package/dist/server/rate-limit/utils.d.ts

@@ -0,0 +1,27 @@
+import { RateLimitController, RateLimitMeta, RateLimitConfigs, ResolvedRateLimitEntry } from '../../types/plugins';
+/**
+ * Resolve rate limit key with substitutions:
+ * - :route → methodName
+ * - :parent → basePath
+ * - :user:{field} → user[field] from auth context (e.g., :user:plan, :user:id)
+ */
+export declare function resolveRateLimitKey(raw: string, methodName: string, basePath: string, user?: any): string;
+/**
+ * Create an in-memory rate limit controller with token-bucket algorithm
+ * Lazy fills bucket on each access
+ */
+export declare function createInMemoryRateLimit(): RateLimitController;
+/**
+ * Pre-handler: normalize → array, resolve keys, lookup config,
+ * call controller.deduct(), return resolved entries + remaining balances
+ */
+export declare function applyRateLimitCheck(meta: RateLimitMeta | undefined, controller: RateLimitController, configs: RateLimitConfigs, methodName: string, basePath: string, user?: any): Promise<{
+    entries: ResolvedRateLimitEntry[];
+    remainingBalances: number[];
+}>;
+/**
+ * Post-handler: refund if statusCode in refundedStatusCodes,
+ * OR if refundSuccessful && 2xx
+ */
+export declare function applyRateLimitRefund(entries: ResolvedRateLimitEntry[], controller: RateLimitController, statusCode: number): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../typescript/src/server/rate-limit/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,mBAAmB,EAEnB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,qBAAqB,CAAA;AAM5B;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,GAAG,GACT,MAAM,CAoBR;AAWD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,mBAAmB,CAoE7D;AAMD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,UAAU,EAAE,mBAAmB,EAC/B,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,GAAG,GACT,OAAO,CAAC;IAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA6B7E;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,sBAAsB,EAAE,EACjC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/server/rate-limit/utils.js

@@ -0,0 +1,126 @@
+import { HttpError } from "../../types/index.js";
+// ============================================================================
+// KEY SUBSTITUTION
+// ============================================================================
+/**
+ * Resolve rate limit key with substitutions:
+ * - :route → methodName
+ * - :parent → basePath
+ * - :user:{field} → user[field] from auth context (e.g., :user:plan, :user:id)
+ */
+export function resolveRateLimitKey(raw, methodName, basePath, user) {
+    let key = raw
+        .replace(':route', methodName)
+        .replace(':parent', basePath);
+    // Replace :user:{field} with user property
+    if (user) {
+        const userMatches = key.match(/:user:(\w+)/g);
+        if (userMatches) {
+            for (const match of userMatches) {
+                const field = match.slice(6); // Remove ':user:'
+                const value = user[field];
+                if (value !== undefined) {
+                    key = key.replace(match, String(value));
+                }
+            }
+        }
+    }
+    return key;
+}
+/**
+ * Create an in-memory rate limit controller with token-bucket algorithm
+ * Lazy fills bucket on each access
+ */
+export function createInMemoryRateLimit() {
+    const buckets = new Map();
+    function refillBucket(key, config) {
+        const now = Date.now();
+        let bucket = buckets.get(key);
+        if (!bucket) {
+            bucket = { balance: config.maxBalance, lastRefillMs: now };
+            buckets.set(key, bucket);
+            return bucket.balance;
+        }
+        const elapsedMs = now - bucket.lastRefillMs;
+        const intervalsElapsed = Math.floor(elapsedMs / config.fillInterval);
+        if (intervalsElapsed > 0) {
+            const tokensGenerated = intervalsElapsed * config.fillAmount;
+            bucket.balance = Math.min(config.maxBalance, bucket.balance + tokensGenerated);
+            bucket.lastRefillMs = now - (elapsedMs % config.fillInterval);
+        }
+        return bucket.balance;
+    }
+    return {
+        check(key, config) {
+            const balance = refillBucket(key, config);
+            return balance;
+        },
+        deduct(key, cost, config) {
+            const balance = refillBucket(key, config);
+            const minBalance = config.minBalance ?? 0;
+            const newBalance = balance - cost;
+            if (newBalance < minBalance) {
+                const deficit = minBalance - newBalance;
+                const intervalsNeeded = Math.ceil(deficit / config.fillAmount);
+                const retryAfterMs = intervalsNeeded * config.fillInterval;
+                throw new HttpError(429, 'Rate limit exceeded', { retryAfterMs });
+            }
+            const bucket = buckets.get(key);
+            bucket.balance = newBalance;
+            return newBalance;
+        },
+        refund(key, cost, config) {
+            let bucket = buckets.get(key);
+            if (!bucket) {
+                bucket = { balance: Math.min(config.maxBalance, cost), lastRefillMs: Date.now() };
+                buckets.set(key, bucket);
+            }
+            else {
+                bucket.balance = Math.min(config.maxBalance, bucket.balance + cost);
+            }
+        },
+    };
+}
+// ============================================================================
+// PIPELINE HELPERS
+// ============================================================================
+/**
+ * Pre-handler: normalize → array, resolve keys, lookup config,
+ * call controller.deduct(), return resolved entries + remaining balances
+ */
+export async function applyRateLimitCheck(meta, controller, configs, methodName, basePath, user) {
+    if (!meta) {
+        return { entries: [], remainingBalances: [] };
+    }
+    const entries = Array.isArray(meta) ? meta : [meta];
+    const resolved = [];
+    const remainingBalances = [];
+    for (const entry of entries) {
+        const rawKey = entry.key ?? ':route';
+        const key = resolveRateLimitKey(rawKey, methodName, basePath, user);
+        const cost = entry.cost ?? 1;
+        const config = entry.config ?? configs[key];
+        if (!config) {
+            throw new Error(`Rate limit config not found for key "${key}". ` +
+                `Define it in server.rateLimit.configs or inline in route metadata.`);
+        }
+        const remaining = await controller.deduct(key, cost, config);
+        resolved.push({ key, cost, config });
+        remainingBalances.push(remaining);
+    }
+    return { entries: resolved, remainingBalances };
+}
+/**
+ * Post-handler: refund if statusCode in refundedStatusCodes,
+ * OR if refundSuccessful && 2xx
+ */
+export async function applyRateLimitRefund(entries, controller, statusCode) {
+    for (const entry of entries) {
+        const shouldRefund = (entry.config.refundedStatusCodes?.includes(statusCode)) ||
+            (entry.config.refundSuccessful && statusCode >= 200 && statusCode < 300);
+        if (shouldRefund) {
+            await controller.refund(entry.key, entry.cost, entry.config);
+        }
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/server/rate-limit/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../typescript/src/server/rate-limit/utils.ts"],"names":[],"mappings":"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"}