@rudderjs/router 1.2.0 → 1.3.0

package/dist/resource.d.ts

@@ -0,0 +1,79 @@
+import type { HttpMethod, MiddlewareHandler } from '@rudderjs/contracts';
+import type { Router, RouteBuilder } from './index.js';
+/** The seven canonical RESTful verbs Laravel's `Route::resource` exposes. */
+export type ResourceVerb = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
+/** @internal — shape of a single row in the verb tables below. */
+export interface ResourceVerbSpec {
+    verb: ResourceVerb;
+    method: HttpMethod;
+    path: (name: string, param: string) => string;
+    nameSuffix: string;
+}
+/** @internal — verb table for `resource()` / `apiResource()`. */
+export declare const RESOURCE_VERBS: readonly ResourceVerbSpec[];
+/** @internal — verb table for `singleton()`. */
+export declare const SINGLETON_VERBS: readonly ResourceVerbSpec[];
+/** @internal — `.creatable()` opt-in for singletons. */
+export declare const SINGLETON_CREATE_VERBS: readonly ResourceVerbSpec[];
+/** @internal — `.destroyable()` opt-in for singletons. */
+export declare const SINGLETON_DESTROY_VERBS: readonly ResourceVerbSpec[];
+/** @internal — apply `only` / `except` to a verb table. */
+export declare function filterVerbs(table: readonly ResourceVerbSpec[], opts: ResourceOptions): readonly ResourceVerbSpec[];
+/**
+ * @internal — naive English singularizer for the default resource param name.
+ * Handles the three patterns Laravel users hit constantly (`posts → post`,
+ * `categories → category`, `boxes → box`). Anything irregular — `people`,
+ * `data`, etc. — should be overridden via the `parameters` option, exactly
+ * as in Laravel.
+ */
+export declare function singularize(name: string): string;
+/**
+ * Options accepted by `router.resource`/`apiResource`/`singleton`.
+ *
+ * - `only`/`except` — restrict the verbs registered.
+ * - `parameters` — override the `:param` segment name for a given resource
+ *   (e.g. `{ posts: 'article' }` → `/posts/:article`).
+ * - `names` — override the generated route names per verb.
+ * - `middleware` — applied to every route registered by the resource.
+ */
+export interface ResourceOptions {
+    only?: readonly ResourceVerb[];
+    except?: readonly ResourceVerb[];
+    parameters?: Record<string, string>;
+    names?: Partial<Record<ResourceVerb, string>>;
+    middleware?: MiddlewareHandler[];
+}
+/**
+ * Returned by `router.resource()`/`apiResource()`. The `builders` array holds
+ * one `RouteBuilder` per registered route in declaration order — apply
+ * `where*()`, additional middleware, or rename individual routes by indexing
+ * directly. The `update` PATCH alias is included as a separate builder
+ * immediately after its PUT counterpart.
+ */
+export declare class ResourceRegistration {
+    readonly builders: RouteBuilder[];
+    constructor(builders: RouteBuilder[]);
+}
+/**
+ * Returned by `router.singleton()`. Adds two opt-in helpers on top of
+ * `ResourceRegistration` for resources that also expose a creation flow
+ * (`.creatable()`) or deletion flow (`.destroyable()`).
+ */
+export declare class SingletonRegistration extends ResourceRegistration {
+    private readonly _router;
+    private readonly _name;
+    private readonly _Ctrl;
+    private readonly _opts;
+    constructor(builders: RouteBuilder[], _router: Router, _name: string, _Ctrl: new () => object, _opts: ResourceOptions);
+    /**
+     * Add `GET /<name>/create` and `POST /<name>` — the create/store half of a
+     * full resource. Skipped for any verb the controller doesn't implement.
+     */
+    creatable(): this;
+    /**
+     * Add `DELETE /<name>` — the destroy half of a full resource. Skipped if
+     * the controller doesn't implement `destroy()`.
+     */
+    destroyable(): this;
+}
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAItD,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEhG,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAQ,YAAY,CAAA;IACxB,MAAM,EAAM,UAAU,CAAA;IACtB,IAAI,EAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACnD,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,iEAAiE;AACjE,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAQrD,CAAA;AAED,gDAAgD;AAChD,eAAO,MAAM,eAAe,EAAE,SAAS,gBAAgB,EAItD,CAAA;AAED,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,EAAE,SAAS,gBAAgB,EAG7D,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,EAAE,SAAS,gBAAgB,EAE9D,CAAA;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAAE,IAAI,EAAE,eAAe,GAAG,SAAS,gBAAgB,EAAE,CAKlH;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAQ,SAAS,YAAY,EAAE,CAAA;IACpC,MAAM,CAAC,EAAM,SAAS,YAAY,EAAE,CAAA;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,KAAK,CAAC,EAAO,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAA;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,oBAAoB;aACH,QAAQ,EAAE,YAAY,EAAE;gBAAxB,QAAQ,EAAE,YAAY,EAAE;CACrD;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,oBAAoB;IAG3D,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAJtB,QAAQ,EAAE,YAAY,EAAE,EACP,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,MAAM,EACvB,KAAK,EAAE,eAAe;IAGzC;;;OAGG;IACH,SAAS,IAAI,IAAI;IAMjB;;;OAGG;IACH,WAAW,IAAI,IAAI;CAKpB"}

package/dist/resource.js

@@ -0,0 +1,104 @@
+/** @internal — verb table for `resource()` / `apiResource()`. */
+export const RESOURCE_VERBS = [
+    { verb: 'index', method: 'GET', path: (n) => `/${n}`, nameSuffix: 'index' },
+    { verb: 'create', method: 'GET', path: (n) => `/${n}/create`, nameSuffix: 'create' },
+    { verb: 'store', method: 'POST', path: (n) => `/${n}`, nameSuffix: 'store' },
+    { verb: 'show', method: 'GET', path: (n, p) => `/${n}/:${p}`, nameSuffix: 'show' },
+    { verb: 'edit', method: 'GET', path: (n, p) => `/${n}/:${p}/edit`, nameSuffix: 'edit' },
+    { verb: 'update', method: 'PUT', path: (n, p) => `/${n}/:${p}`, nameSuffix: 'update' },
+    { verb: 'destroy', method: 'DELETE', path: (n, p) => `/${n}/:${p}`, nameSuffix: 'destroy' },
+];
+/** @internal — verb table for `singleton()`. */
+export const SINGLETON_VERBS = [
+    { verb: 'show', method: 'GET', path: (n) => `/${n}`, nameSuffix: 'show' },
+    { verb: 'edit', method: 'GET', path: (n) => `/${n}/edit`, nameSuffix: 'edit' },
+    { verb: 'update', method: 'PUT', path: (n) => `/${n}`, nameSuffix: 'update' },
+];
+/** @internal — `.creatable()` opt-in for singletons. */
+export const SINGLETON_CREATE_VERBS = [
+    { verb: 'create', method: 'GET', path: (n) => `/${n}/create`, nameSuffix: 'create' },
+    { verb: 'store', method: 'POST', path: (n) => `/${n}`, nameSuffix: 'store' },
+];
+/** @internal — `.destroyable()` opt-in for singletons. */
+export const SINGLETON_DESTROY_VERBS = [
+    { verb: 'destroy', method: 'DELETE', path: (n) => `/${n}`, nameSuffix: 'destroy' },
+];
+/** @internal — apply `only` / `except` to a verb table. */
+export function filterVerbs(table, opts) {
+    let verbs = table;
+    if (opts.only) {
+        const allow = new Set(opts.only);
+        verbs = verbs.filter(v => allow.has(v.verb));
+    }
+    if (opts.except) {
+        const deny = new Set(opts.except);
+        verbs = verbs.filter(v => !deny.has(v.verb));
+    }
+    return verbs;
+}
+/**
+ * @internal — naive English singularizer for the default resource param name.
+ * Handles the three patterns Laravel users hit constantly (`posts → post`,
+ * `categories → category`, `boxes → box`). Anything irregular — `people`,
+ * `data`, etc. — should be overridden via the `parameters` option, exactly
+ * as in Laravel.
+ */
+export function singularize(name) {
+    if (/[^aeiou]ies$/i.test(name))
+        return name.slice(0, -3) + 'y'; // categories → category
+    if (/(s|x|z|ch|sh)es$/i.test(name))
+        return name.slice(0, -2); // boxes → box
+    if (/s$/i.test(name) && !/ss$/i.test(name))
+        return name.slice(0, -1); // posts → post
+    return name;
+}
+/**
+ * Returned by `router.resource()`/`apiResource()`. The `builders` array holds
+ * one `RouteBuilder` per registered route in declaration order — apply
+ * `where*()`, additional middleware, or rename individual routes by indexing
+ * directly. The `update` PATCH alias is included as a separate builder
+ * immediately after its PUT counterpart.
+ */
+export class ResourceRegistration {
+    builders;
+    constructor(builders) {
+        this.builders = builders;
+    }
+}
+/**
+ * Returned by `router.singleton()`. Adds two opt-in helpers on top of
+ * `ResourceRegistration` for resources that also expose a creation flow
+ * (`.creatable()`) or deletion flow (`.destroyable()`).
+ */
+export class SingletonRegistration extends ResourceRegistration {
+    _router;
+    _name;
+    _Ctrl;
+    _opts;
+    constructor(builders, _router, _name, _Ctrl, _opts) {
+        super(builders);
+        this._router = _router;
+        this._name = _name;
+        this._Ctrl = _Ctrl;
+        this._opts = _opts;
+    }
+    /**
+     * Add `GET /<name>/create` and `POST /<name>` — the create/store half of a
+     * full resource. Skipped for any verb the controller doesn't implement.
+     */
+    creatable() {
+        const reg = this._router._registerResource(this._name, this._Ctrl, SINGLETON_CREATE_VERBS, this._opts);
+        this.builders.push(...reg.builders);
+        return this;
+    }
+    /**
+     * Add `DELETE /<name>` — the destroy half of a full resource. Skipped if
+     * the controller doesn't implement `destroy()`.
+     */
+    destroyable() {
+        const reg = this._router._registerResource(this._name, this._Ctrl, SINGLETON_DESTROY_VERBS, this._opts);
+        this.builders.push(...reg.builders);
+        return this;
+    }
+}
+//# sourceMappingURL=resource.js.map

package/dist/resource.js.map

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

package/dist/typed-routes.d.ts

@@ -0,0 +1,83 @@
+import type { AppRequest, AppResponse } from '@rudderjs/contracts';
+/**
+ * Parse a single `:name` (or `:name?`, or `:name{regex}`, or `:name?{regex}`)
+ * out of the head of a string. Returns `{ name, optional, rest }` or `never`
+ * if no name letter follows the `:`.
+ */
+type ParseParam<S extends string> = S extends `${infer Head}${infer Tail}` ? Head extends Letter ? AccumName<Tail, Head> : never : never;
+type Letter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '_';
+type AccumName<S extends string, Acc extends string> = S extends `${infer Head}${infer Tail}` ? Head extends Letter ? AccumName<Tail, `${Acc}${Head}`> : FinishName<S, Acc> : FinishName<S, Acc>;
+type FinishName<S extends string, Name extends string> = S extends `?${infer Rest}` ? {
+    name: Name;
+    optional: true;
+    rest: StripBraceBlock<Rest>;
+} : {
+    name: Name;
+    optional: false;
+    rest: StripBraceBlock<S>;
+};
+/** Skip a `{...}` regex constraint block (single level; mirrors router's parser). */
+type StripBraceBlock<S extends string> = S extends `{${infer _Body}}${infer Rest}` ? Rest : S;
+/**
+ * Walk the path and accumulate every `:param` into a union of
+ * `{ name; optional }` records.
+ */
+type ScanParams<P extends string, Acc = never> = P extends `${infer _Head}:${infer Rest}` ? ParseParam<Rest> extends {
+    name: infer N;
+    optional: infer O;
+    rest: infer R;
+} ? N extends string ? R extends string ? ScanParams<R, Acc | {
+    name: N;
+    optional: O;
+}> : Acc : Acc : ScanParams<Rest, Acc> : Acc;
+/**
+ * Map the param union to an object. Optional params become optional keys.
+ *
+ * Tricks used here:
+ * - `as` re-keys the mapped type so the property name is the captured `name`.
+ * - Splitting required vs optional via intersection lets us mark optional
+ *   keys with `?:` while keeping required ones as `:`. TS doesn't allow
+ *   conditional optionality inside a single mapped type.
+ */
+type ParamUnion<P extends string> = ScanParams<P>;
+type RequiredParams<P extends string> = {
+    [U in Extract<ParamUnion<P>, {
+        optional: false;
+    }> as U['name']]: string;
+};
+type OptionalParams<P extends string> = {
+    [U in Extract<ParamUnion<P>, {
+        optional: true;
+    }> as U['name']]?: string;
+};
+/**
+ * Object shape of `req.params` for a literal route path.
+ *
+ * @example
+ * type T1 = ExtractParams<'/users/:id'>                // { id: string }
+ * type T2 = ExtractParams<'/users/:id/posts/:postId'>  // { id: string; postId: string }
+ * type T3 = ExtractParams<'/files/:name?'>             // { name?: string }
+ * type T4 = ExtractParams<'/health'>                   // {}
+ */
+export type ExtractParams<P extends string> = Prettify<RequiredParams<P> & OptionalParams<P>>;
+/** Flatten an intersection into a single object literal for nicer hovers. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * `AppRequest` with `params` and `query` overridden to the inferred shapes.
+ * All other fields (including module-augmented `user`, `session`, `token`)
+ * are inherited via `Omit + extend`.
+ */
+export interface TypedRequest<P extends Record<string, string | undefined> = Record<string, string>, Q = Record<string, string>> extends Omit<AppRequest, 'params' | 'query'> {
+    params: P;
+    query: Q;
+}
+/**
+ * Handler whose `req.params` is derived from the literal path `P`, and whose
+ * `req.query` is `Q` (defaulted to `Record<string, string>`; replaced via
+ * `{ query: schema }` opts in the route declaration).
+ */
+export type TypedHandler<P extends string, Q = Record<string, string>> = (req: TypedRequest<ExtractParams<P>, Q>, res: AppResponse) => unknown | Promise<unknown>;
+export {};
+//# sourceMappingURL=typed-routes.d.ts.map

package/dist/typed-routes.d.ts.map

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

package/dist/typed-routes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=typed-routes.js.map

package/dist/typed-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-routes.js","sourceRoot":"","sources":["../src/typed-routes.ts"],"names":[],"mappings":""}

package/dist/typed-routes.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=typed-routes.test-d.d.ts.map

package/dist/typed-routes.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-routes.test-d.d.ts","sourceRoot":"","sources":["../src/typed-routes.test-d.ts"],"names":[],"mappings":"AAgHA,OAAO,EAAE,CAAA"}

package/dist/typed-routes.test-d.js

@@ -0,0 +1,77 @@
+/**
+ * Type-only test for `ExtractParams<P>` + typed handler signatures.
+ *
+ * Compiled by `pnpm typecheck` (and the test build); failing type assertions
+ * surface as tsc errors. No runtime tests live here — Node's `--test` glob
+ * excludes `*.test-d.js`.
+ */
+import { z } from 'zod';
+import { Router } from './index.js';
+const router = new Router();
+const check = () => undefined;
+check();
+check();
+check();
+check();
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+check();
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+check();
+// ─── Handler typing (positive) ─────────────────────────────
+router.get('/users/:id', (req) => {
+    const id = req.params.id;
+    return id;
+});
+router.post('/users/:id/posts/:postId', (req) => {
+    const id = req.params.id;
+    const postId = req.params.postId;
+    return { id, postId };
+});
+router.get('/files/:name?', (req) => {
+    const name = req.params.name;
+    return name;
+});
+router.get('/health', (req) => {
+    // No params — `req.params` is `{}`. Reading any key would be an error.
+    return req.params;
+});
+// ─── Handler typing (negative) ─────────────────────────────
+router.get('/users/:id', (req) => {
+    // @ts-expect-error `notReal` is not a declared param
+    return req.params.notReal;
+});
+router.get('/users/:id', (req) => {
+    // @ts-expect-error optional access pattern on required param — `id` is `string`, not nullable
+    const id = req.params.id;
+    return id;
+});
+router.get('/files/:name?', (req) => {
+    // @ts-expect-error `name` is `string | undefined`, not assignable to `string`
+    const name = req.params.name;
+    return name;
+});
+// ─── Opts form: req.query inferred from Zod schema ─────────
+router.get('/users/:id', { query: z.object({ page: z.coerce.number(), q: z.string() }) }, (req) => {
+    const id = req.params.id;
+    const page = req.query.page;
+    const q = req.query.q;
+    return { id, page, q };
+});
+router.get('/search', { query: z.object({ q: z.string() }) }, (req) => {
+    // @ts-expect-error `page` is not in the query schema
+    return req.query.page;
+});
+router.get('/search', { query: z.object({ q: z.string() }) }, (req) => {
+    // @ts-expect-error `q` is `string`, not `number`
+    const q = req.query.q;
+    return q;
+});
+// ─── Other AppRequest fields still accessible ──────────────
+router.get('/health', (req) => {
+    const method = req.method;
+    const url = req.url;
+    const headers = req.headers;
+    const query = req.query;
+    return { method, url, headers, query };
+});
+//# sourceMappingURL=typed-routes.test-d.js.map

package/dist/typed-routes.test-d.js.map

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

package/dist/url-signing.d.ts

@@ -0,0 +1,46 @@
+import type { AppRequest, MiddlewareHandler } from '@rudderjs/contracts';
+export declare class Url {
+    /**
+     * Override the HMAC signing key used for signed URLs.
+     * Falls back to `process.env.APP_KEY`.
+     */
+    static setKey(key: string): void;
+    /** The full URL of the current request. */
+    static current(req: AppRequest): string;
+    /** The previous URL from the `Referer` header, or `fallback`. */
+    static previous(req: AppRequest, fallback?: string): string;
+    /**
+     * Generate a signed URL for a named route.
+     *
+     * @example
+     * Url.signedRoute('invoice.download', { id: 42 })
+     * // → '/invoice/42?signature=abc123'
+     */
+    static signedRoute(name: string, params?: Record<string, string | number>, expiresAt?: Date): string;
+    /**
+     * Generate a signed URL that expires after `seconds` seconds.
+     *
+     * @example
+     * Url.temporarySignedRoute('invoice.download', 3600, { id: 42 })
+     * // → '/invoice/42?expires=1234567890&signature=abc123'
+     */
+    static temporarySignedRoute(name: string, seconds: number, params?: Record<string, string | number>): string;
+    /**
+     * Sign an arbitrary path string.
+     * Appends `?signature=...` (and `?expires=...` if `expiresAt` given).
+     */
+    static sign(path: string, expiresAt?: Date): string;
+    /**
+     * Return `true` if the request has a valid (and non-expired) signature.
+     */
+    static isValidSignature(req: AppRequest): boolean;
+}
+/**
+ * Middleware that verifies a signed URL signature.
+ * Responds with 403 if the signature is missing, invalid, or expired.
+ *
+ * @example
+ * router.get('/invoice/:id/download', handler, [ValidateSignature()])
+ */
+export declare function ValidateSignature(): MiddlewareHandler;
+//# sourceMappingURL=url-signing.d.ts.map

package/dist/url-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-signing.d.ts","sourceRoot":"","sources":["../src/url-signing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AA6CxE,qBAAa,GAAG;IACd;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC,2CAA2C;IAC3C,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM;IAIvC,iEAAiE;IACjE,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,SAAM,GAAG,MAAM;IAIxD;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,CAChB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAM,EAC5C,SAAS,CAAC,EAAE,IAAI,GACf,MAAM;IAIT;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAM,GAC3C,MAAM;IAIT;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM;IAcnD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;CA2BlD;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAOrD"}

package/dist/url-signing.js

@@ -0,0 +1,133 @@
+import { route } from './index.js';
+// ─── node:crypto lazy load ─────────────────────────────────
+//
+// Lazy-load node:crypto to avoid bundling it into the client. Only used by
+// Url (signed URLs) and ValidateSignature — server-only features. The
+// fire-and-forget import preloads on server and is a no-op in the browser
+// where `globalThis.process` is undefined.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _crypto;
+if (typeof globalThis.process !== 'undefined') {
+    import(/* @vite-ignore */ 'node:crypto').then(m => { _crypto = m; }).catch(() => { });
+}
+// ─── Signing key + helpers ─────────────────────────────────
+let _urlKey = '';
+function _getSigningKey() {
+    const key = _urlKey || process.env['APP_KEY'] || '';
+    if (!key)
+        throw new Error('[RudderJS] No signing key configured. Set APP_KEY in your .env or call Url.setKey().');
+    return key;
+}
+function _splitPath(path) {
+    const idx = path.indexOf('?');
+    return idx === -1 ? [path, ''] : [path.slice(0, idx), path.slice(idx + 1)];
+}
+function _computeSignature(pathname, params) {
+    // Sort params for deterministic signing (exclude 'signature' itself)
+    const sorted = new URLSearchParams([...params.entries()]
+        .filter(([k]) => k !== 'signature')
+        .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+    const toSign = sorted.size > 0 ? `${pathname}?${sorted.toString()}` : pathname;
+    if (!_crypto)
+        throw new Error('[RudderJS Router] node:crypto not available — Url signing requires a server environment.');
+    return _crypto.createHmac('sha256', _getSigningKey()).update(toSign).digest('hex');
+}
+// ─── Url ───────────────────────────────────────────────────
+export class Url {
+    /**
+     * Override the HMAC signing key used for signed URLs.
+     * Falls back to `process.env.APP_KEY`.
+     */
+    static setKey(key) {
+        _urlKey = key;
+    }
+    /** The full URL of the current request. */
+    static current(req) {
+        return req.url;
+    }
+    /** The previous URL from the `Referer` header, or `fallback`. */
+    static previous(req, fallback = '/') {
+        return req.headers['referer'] ?? fallback;
+    }
+    /**
+     * Generate a signed URL for a named route.
+     *
+     * @example
+     * Url.signedRoute('invoice.download', { id: 42 })
+     * // → '/invoice/42?signature=abc123'
+     */
+    static signedRoute(name, params = {}, expiresAt) {
+        return Url.sign(route(name, params), expiresAt);
+    }
+    /**
+     * Generate a signed URL that expires after `seconds` seconds.
+     *
+     * @example
+     * Url.temporarySignedRoute('invoice.download', 3600, { id: 42 })
+     * // → '/invoice/42?expires=1234567890&signature=abc123'
+     */
+    static temporarySignedRoute(name, seconds, params = {}) {
+        return Url.signedRoute(name, params, new Date(Date.now() + seconds * 1000));
+    }
+    /**
+     * Sign an arbitrary path string.
+     * Appends `?signature=...` (and `?expires=...` if `expiresAt` given).
+     */
+    static sign(path, expiresAt) {
+        const [pathname, search] = _splitPath(path);
+        const params = new URLSearchParams(search);
+        if (expiresAt) {
+            params.set('expires', String(Math.floor(expiresAt.getTime() / 1000)));
+        }
+        const sig = _computeSignature(pathname, params);
+        params.set('signature', sig);
+        return `${pathname}?${params.toString()}`;
+    }
+    /**
+     * Return `true` if the request has a valid (and non-expired) signature.
+     */
+    static isValidSignature(req) {
+        // `req.url` may be a full URL (Hono adapter populates protocol+host+path+query)
+        // or a bare path. `Url.sign(path)` only ever signs the pathname, so verification
+        // must hash the same shape. Use the URL parser so both forms collapse to a
+        // pathname + searchParams pair.
+        const u = new URL(req.url, 'http://placeholder.local');
+        const pathname = u.pathname;
+        const params = u.searchParams;
+        const signature = params.get('signature');
+        if (!signature)
+            return false;
+        // Check expiry before touching the signature
+        const expires = params.get('expires');
+        if (expires !== null) {
+            const expiry = parseInt(expires, 10);
+            if (isNaN(expiry) || Date.now() / 1000 > expiry)
+                return false;
+        }
+        const expected = _computeSignature(pathname, params);
+        if (!_crypto)
+            return signature === expected;
+        const sigBuf = Buffer.from(signature);
+        const expBuf = Buffer.from(expected);
+        if (sigBuf.length !== expBuf.length)
+            return false;
+        return _crypto.timingSafeEqual(sigBuf, expBuf);
+    }
+}
+// ─── ValidateSignature middleware ───────────────────────────
+/**
+ * Middleware that verifies a signed URL signature.
+ * Responds with 403 if the signature is missing, invalid, or expired.
+ *
+ * @example
+ * router.get('/invoice/:id/download', handler, [ValidateSignature()])
+ */
+export function ValidateSignature() {
+    return async (req, res, next) => {
+        if (!Url.isValidSignature(req)) {
+            return res.status(403).json({ message: 'Invalid or expired URL signature.' });
+        }
+        await next();
+    };
+}
+//# sourceMappingURL=url-signing.js.map

package/dist/url-signing.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudderjs/router",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -8,6 +8,9 @@
     "directory": "packages/router"
   },
   "type": "module",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
   "files": [
     "dist",
     "boost"
@@ -27,7 +30,8 @@
   },
   "dependencies": {
     "reflect-metadata": "^0.2.2",
-    "@rudderjs/contracts": "^1.4.0"
+    "zod": "^4.0.0",
+    "@rudderjs/contracts": "^1.7.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -42,6 +46,6 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
     "clean": "rm -rf dist",
-    "test": "tsc -p tsconfig.test.json && node --test dist-test/index.test.js dist-test/resource.test.js; EXIT=$?; rm -rf dist-test; exit $EXIT"
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/index.test.js dist-test/resource.test.js dist-test/query-validator.test.js; EXIT=$?; rm -rf dist-test; exit $EXIT"
   }
 }