@c9up/ream 0.1.3

package/dist/http/Exception.js

@@ -0,0 +1,228 @@
+/**
+ * Exception system — AdonisJS-compatible exception handling.
+ *
+ * - Exception: base class with self-handling support
+ * - ExceptionHandler: global exception handler with content negotiation
+ * - Built-in E_* exceptions
+ */
+/**
+ * Base exception class. Extend this to create self-handling exceptions.
+ *
+ * Usage:
+ *   throw new Exception('Something went wrong', { status: 400, code: 'E_BAD_REQUEST' })
+ *
+ * Self-handled exception:
+ *   class PaymentFailed extends Exception {
+ *     static status = 402
+ *     static code = 'E_PAYMENT_FAILED'
+ *     async handle(error: this, ctx: HttpContext) {
+ *       ctx.response.status(402).json({ error: 'Payment failed' })
+ *     }
+ *     async report(error: this, ctx: HttpContext) {
+ *       logger.error('Payment failed', { userId: ctx.auth.user?.id })
+ *     }
+ *   }
+ */
+export class Exception extends Error {
+    static status = 500;
+    static code = 'E_UNKNOWN';
+    status;
+    code;
+    constructor(message, options) {
+        super(message);
+        this.name = this.constructor.name;
+        // biome-ignore lint/suspicious/noExplicitAny: this.constructor is typed as Function; subclass pattern requires the cast
+        const ctor = this.constructor;
+        this.status = options?.status ?? ctor.status;
+        this.code = options?.code ?? ctor.code;
+    }
+}
+// ─── Built-in exceptions ──────────────────────────────────
+export class E_ROUTE_NOT_FOUND extends Exception {
+    static status = 404;
+    static code = 'E_ROUTE_NOT_FOUND';
+    constructor(method, path) {
+        super(`Route not found: ${method} ${path}`, { status: 404, code: 'E_ROUTE_NOT_FOUND' });
+    }
+}
+export class E_UNAUTHORIZED extends Exception {
+    static status = 401;
+    static code = 'E_UNAUTHORIZED';
+    constructor(message = 'Authentication required') {
+        super(message, { status: 401, code: 'E_UNAUTHORIZED' });
+    }
+    handle(_error, ctx) {
+        ctx.response.status(401).json({ error: { code: 'E_UNAUTHORIZED', message: this.message } });
+    }
+}
+export class E_FORBIDDEN extends Exception {
+    static status = 403;
+    static code = 'E_FORBIDDEN';
+    required;
+    constructor(message = 'Insufficient permissions', required) {
+        super(message, { status: 403, code: 'E_FORBIDDEN' });
+        this.required = required;
+    }
+    handle(_error, ctx) {
+        ctx.response.status(403).json({
+            error: {
+                code: 'E_FORBIDDEN',
+                message: this.message,
+                ...(this.required ? { required: this.required } : {}),
+            },
+        });
+    }
+}
+export class E_VALIDATION_ERROR extends Exception {
+    static status = 422;
+    static code = 'E_VALIDATION_ERROR';
+    errors;
+    constructor(errors) {
+        super('Validation failed', { status: 422, code: 'E_VALIDATION_ERROR' });
+        this.errors = errors;
+    }
+    handle(_error, ctx) {
+        ctx.response.status(422).json({ errors: this.errors });
+    }
+}
+export class E_ROW_NOT_FOUND extends Exception {
+    static status = 404;
+    static code = 'E_ROW_NOT_FOUND';
+    constructor(model) {
+        super(model ? `${model} not found` : 'Resource not found', {
+            status: 404,
+            code: 'E_ROW_NOT_FOUND',
+        });
+    }
+    handle(_error, ctx) {
+        ctx.response.status(404).json({ error: { code: 'E_ROW_NOT_FOUND', message: this.message } });
+    }
+}
+export class E_HTTP_EXCEPTION extends Exception {
+    constructor(message, status) {
+        super(message, { status, code: 'E_HTTP_EXCEPTION' });
+    }
+}
+// ─── ExceptionHandler ─────────────────────────────────────
+/**
+ * Global exception handler — catches all unhandled exceptions and converts
+ * them to HTTP responses.
+ *
+ * Extend this in your app:
+ *   export default class Handler extends ExceptionHandler {
+ *     protected debug = app.inDev
+ *     protected ignoreStatuses = [400, 401, 404, 422]
+ *   }
+ *
+ * Flow:
+ * 1. If exception has handle() → self-handled (bypass global)
+ * 2. Else → this.handle() → content negotiation (JSON or HTML)
+ * 3. Then → this.report() → logging/monitoring
+ */
+export class ExceptionHandler {
+    debug;
+    ignoreStatuses = [400, 401, 404, 422];
+    ignoreCodes = [];
+    constructor(debug = false) {
+        this.debug = debug;
+    }
+    /** Convert an exception to an HTTP response. */
+    async handle(error, ctx) {
+        // Self-handled exceptions take over entirely.
+        if (error instanceof Exception && typeof error.handle === 'function') {
+            await error.handle(error, ctx);
+            return;
+        }
+        const { status, code } = extractErrorMeta(error);
+        const message = this.#errorMessage(error);
+        if (wantsJson(ctx)) {
+            this.#sendJsonError(ctx, status, code, message, error);
+        }
+        else {
+            this.#sendHtmlError(ctx, status, message);
+        }
+    }
+    /** Pick the user-facing message — full detail only in debug mode. */
+    #errorMessage(error) {
+        if (this.debug && error instanceof Error)
+            return error.message;
+        if (error instanceof Exception)
+            return error.message;
+        return 'An internal error occurred';
+    }
+    #sendJsonError(ctx, status, code, message, error) {
+        const errorPayload = { code, message };
+        if (this.debug && error instanceof Error && error.stack) {
+            errorPayload.stack = error.stack;
+        }
+        ctx.response.status(status).json({ error: errorPayload });
+    }
+    #sendHtmlError(ctx, status, message) {
+        ctx.response
+            .status(status)
+            .type('text/html; charset=utf-8')
+            .send(`<!DOCTYPE html><html><head><title>Error ${status}</title></head>` +
+            `<body><h1>${status}</h1><p>${escapeHtml(message)}</p></body></html>`);
+    }
+    /** Log/report an exception. Override for custom monitoring. */
+    async report(error, ctx) {
+        if (error instanceof Exception) {
+            if (this.ignoreStatuses.includes(error.status))
+                return;
+            if (this.ignoreCodes.includes(error.code))
+                return;
+        }
+        // Self-reported exceptions
+        if (error instanceof Exception && typeof error.report === 'function') {
+            await error.report(error, ctx);
+            return;
+        }
+        // Default: log to stderr
+        const context = this.context(ctx);
+        if (error instanceof Error) {
+            console.error(`[${new Date().toISOString()}] ${error.message}`, context, error.stack);
+        }
+        else {
+            console.error(`[${new Date().toISOString()}] Unknown error:`, error, context);
+        }
+    }
+    /** Provide additional context for error reports. Override for custom data. */
+    context(ctx) {
+        return {
+            requestId: ctx.id,
+            method: ctx.request.method(),
+            url: ctx.request.url(),
+            userId: ctx.auth.user?.id,
+        };
+    }
+}
+/** Extract status + code from an Exception, ReamError, or duck-typed error. */
+function extractErrorMeta(error) {
+    let status = 500;
+    let code = 'E_UNKNOWN';
+    if (error instanceof Exception) {
+        status = error.status;
+        code = error.code;
+    }
+    else if (error !== null && typeof error === 'object') {
+        if ('status' in error && typeof error.status === 'number')
+            status = error.status;
+        if ('code' in error && typeof error.code === 'string')
+            code = error.code;
+    }
+    return { status, code };
+}
+/** Content negotiation: JSON unless the client explicitly prefers HTML. */
+function wantsJson(ctx) {
+    return (ctx.request.accepts(['json', 'html']) === 'json' ||
+        (ctx.request.header('accept')?.includes('application/json') ?? false) ||
+        !ctx.request.header('accept')?.includes('text/html'));
+}
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+//# sourceMappingURL=Exception.js.map

package/dist/http/Exception.js.map

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

package/dist/http/HttpContext.d.ts

@@ -0,0 +1,69 @@
+/**
+ * HttpContext — fully typed HTTP context for handlers, middleware, and controllers.
+ *
+ * Replaces Context.http() for HTTP transport. Always has request + response (no ! assertions).
+ * Compatible with AdonisJS destructuring: { request, response, auth, params }
+ *
+ * @implements FR21
+ */
+import type { Emitter } from '../events/Emitter.js';
+import type { RouteUrlResolver } from './RedirectBuilder.js';
+import type { RawRequest } from './Request.js';
+import { Request } from './Request.js';
+import { Response } from './Response.js';
+export interface AuthState {
+    authenticated: boolean;
+    user?: {
+        id: string;
+        email?: string;
+        roles?: string[];
+        permissions?: string[];
+        [key: string]: unknown;
+    };
+    roles?: string[];
+    permissions?: string[];
+}
+export interface RouteInfo {
+    pattern: string;
+    name?: string;
+    middleware: string[];
+    /**
+     * Controller class + method that owns this route, when the route was
+     * registered as `router.get('/x', SomeController, 'method')` (vs an
+     * inline arrow handler). Middleware that reads decorator metadata —
+     * `@Guard`, `@Permission`, `@Role` (Warden), `@Meta` (Photon) —
+     * needs both fields. Absent when the route handler is an inline
+     * function. Populated by `HttpKernel` from `match.route.controller`.
+     */
+    controller?: object;
+    action?: string;
+}
+export declare class HttpContext {
+    #private;
+    /** Unique request/correlation ID. */
+    readonly id: string;
+    /** Typed HTTP request. */
+    readonly request: Request;
+    /** Typed HTTP response builder. */
+    readonly response: Response;
+    /** Route parameters extracted from the URL pattern. */
+    readonly params: Record<string, string>;
+    /** Information about the matched route. */
+    readonly route: RouteInfo;
+    /** Authentication state — populated by auth middleware. */
+    auth: AuthState;
+    /** Detected locale. */
+    locale: string;
+    /** Per-request key-value store (for middleware to pass data downstream). */
+    readonly store: Map<string, unknown>;
+    /**
+     * The event bus emitter, when the app registered `EventsProvider`. Lets a
+     * handler emit/subscribe without resolving from the container:
+     * `ctx.events?.emit('user:updated', user)`. Undefined when events aren't wired.
+     */
+    events?: Emitter;
+    constructor(id: string, rawRequest: RawRequest, params: Record<string, string>, route: RouteInfo);
+    /** @internal Set the route URL resolver (injected by HttpKernel from Router). */
+    setRouteUrlResolver(resolver: RouteUrlResolver): void;
+}
+//# sourceMappingURL=HttpContext.d.ts.map

package/dist/http/HttpContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpContext.d.ts","sourceRoot":"","sources":["../../src/http/HttpContext.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,OAAO,CAAA;IACtB,IAAI,CAAC,EAAE;QACL,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;QACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,qBAAa,WAAW;;IACtB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAE3B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEvC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IAEzB,2DAA2D;IAC3D,IAAI,EAAE,SAAS,CAA2B;IAE1C,uBAAuB;IACvB,MAAM,SAAO;IAEb,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAY;IAEhD;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;gBAMd,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,KAAK,EAAE,SAAS;IAmBlB,iFAAiF;IACjF,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;CAGtD"}

package/dist/http/HttpContext.js

@@ -0,0 +1,55 @@
+/**
+ * HttpContext — fully typed HTTP context for handlers, middleware, and controllers.
+ *
+ * Replaces Context.http() for HTTP transport. Always has request + response (no ! assertions).
+ * Compatible with AdonisJS destructuring: { request, response, auth, params }
+ *
+ * @implements FR21
+ */
+import { RedirectBuilder } from './RedirectBuilder.js';
+import { Request } from './Request.js';
+import { Response } from './Response.js';
+export class HttpContext {
+    /** Unique request/correlation ID. */
+    id;
+    /** Typed HTTP request. */
+    request;
+    /** Typed HTTP response builder. */
+    response;
+    /** Route parameters extracted from the URL pattern. */
+    params;
+    /** Information about the matched route. */
+    route;
+    /** Authentication state — populated by auth middleware. */
+    auth = { authenticated: false };
+    /** Detected locale. */
+    locale = 'en';
+    /** Per-request key-value store (for middleware to pass data downstream). */
+    store = new Map();
+    /**
+     * The event bus emitter, when the app registered `EventsProvider`. Lets a
+     * handler emit/subscribe without resolving from the container:
+     * `ctx.events?.emit('user:updated', user)`. Undefined when events aren't wired.
+     */
+    events;
+    /** Route URL resolver for redirect().toRoute(). */
+    #routeUrlResolver;
+    constructor(id, rawRequest, params, route) {
+        this.id = id;
+        this.params = params;
+        this.route = route;
+        this.request = new Request(rawRequest, params);
+        this.response = new Response();
+        // Wire redirect builder with request context
+        this.response.setRedirectFactory(() => new RedirectBuilder(this.response, {
+            requestUrl: this.request.url(),
+            requestReferer: this.request.header('referer'),
+            routeUrlResolver: this.#routeUrlResolver,
+        }));
+    }
+    /** @internal Set the route URL resolver (injected by HttpKernel from Router). */
+    setRouteUrlResolver(resolver) {
+        this.#routeUrlResolver = resolver;
+    }
+}
+//# sourceMappingURL=HttpContext.js.map

package/dist/http/HttpContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpContext.js","sourceRoot":"","sources":["../../src/http/HttpContext.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AA+BxC,MAAM,OAAO,WAAW;IACtB,qCAAqC;IAC5B,EAAE,CAAQ;IAEnB,0BAA0B;IACjB,OAAO,CAAS;IAEzB,mCAAmC;IAC1B,QAAQ,CAAU;IAE3B,uDAAuD;IAC9C,MAAM,CAAwB;IAEvC,2CAA2C;IAClC,KAAK,CAAW;IAEzB,2DAA2D;IAC3D,IAAI,GAAc,EAAE,aAAa,EAAE,KAAK,EAAE,CAAA;IAE1C,uBAAuB;IACvB,MAAM,GAAG,IAAI,CAAA;IAEb,4EAA4E;IACnE,KAAK,GAAyB,IAAI,GAAG,EAAE,CAAA;IAEhD;;;;OAIG;IACH,MAAM,CAAU;IAEhB,mDAAmD;IACnD,iBAAiB,CAAmB;IAEpC,YACE,EAAU,EACV,UAAsB,EACtB,MAA8B,EAC9B,KAAgB;QAEhB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;QACZ,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;QAC9C,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAA;QAE9B,6CAA6C;QAC7C,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAC9B,GAAG,EAAE,CACH,IAAI,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE;YACjC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YAC9B,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;YAC9C,gBAAgB,EAAE,IAAI,CAAC,iBAAiB;SACzC,CAAC,CACL,CAAA;IACH,CAAC;IAED,iFAAiF;IACjF,mBAAmB,CAAC,QAA0B;QAC5C,IAAI,CAAC,iBAAiB,GAAG,QAAQ,CAAA;IACnC,CAAC;CACF"}

package/dist/http/RedirectBuilder.d.ts

@@ -0,0 +1,31 @@
+/**
+ * RedirectBuilder — fluent API for building redirect responses.
+ *
+ * Usage:
+ *   response.redirect().toPath('/login')
+ *   response.redirect().status(301).toPath('/new-url')
+ *   response.redirect().back()
+ *   response.redirect().withQs({ page: '2' }).toPath('/results')
+ *   response.redirect().toRoute('posts.show', { id: '42' })
+ */
+import type { Response } from './Response.js';
+export type RouteUrlResolver = (name: string, params?: Record<string, string>) => string;
+export declare class RedirectBuilder {
+    #private;
+    constructor(response: Response, options?: {
+        requestUrl?: string;
+        requestReferer?: string;
+        routeUrlResolver?: RouteUrlResolver;
+    });
+    /** Set redirect status code. */
+    status(code: number): this;
+    /** Forward current query string to the redirect target. */
+    withQs(qs?: Record<string, string>): this;
+    /** Redirect to an absolute or relative path. */
+    toPath(path: string): void;
+    /** Redirect to a named route. */
+    toRoute(name: string, params?: Record<string, string>): void;
+    /** Redirect back to the previous page (Referer header). */
+    back(fallback?: string): void;
+}
+//# sourceMappingURL=RedirectBuilder.d.ts.map

package/dist/http/RedirectBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedirectBuilder.d.ts","sourceRoot":"","sources":["../../src/http/RedirectBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAA;AAExF,qBAAa,eAAe;;gBAUxB,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;KACpC;IAQH,gCAAgC;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK1B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IASzC,gDAAgD;IAChD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO1B,iCAAiC;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAQ5D,2DAA2D;IAC3D,IAAI,CAAC,QAAQ,SAAM,GAAG,IAAI;CAgB3B"}

package/dist/http/RedirectBuilder.js

@@ -0,0 +1,75 @@
+/**
+ * RedirectBuilder — fluent API for building redirect responses.
+ *
+ * Usage:
+ *   response.redirect().toPath('/login')
+ *   response.redirect().status(301).toPath('/new-url')
+ *   response.redirect().back()
+ *   response.redirect().withQs({ page: '2' }).toPath('/results')
+ *   response.redirect().toRoute('posts.show', { id: '42' })
+ */
+export class RedirectBuilder {
+    #response;
+    #status = 302;
+    #qs = null;
+    #forwardQs = false;
+    #requestUrl;
+    #requestReferer;
+    #routeUrlResolver;
+    constructor(response, options) {
+        this.#response = response;
+        this.#requestUrl = options?.requestUrl;
+        this.#requestReferer = options?.requestReferer;
+        this.#routeUrlResolver = options?.routeUrlResolver;
+    }
+    /** Set redirect status code. */
+    status(code) {
+        this.#status = code;
+        return this;
+    }
+    /** Forward current query string to the redirect target. */
+    withQs(qs) {
+        if (qs) {
+            this.#qs = qs;
+        }
+        else {
+            this.#forwardQs = true;
+        }
+        return this;
+    }
+    /** Redirect to an absolute or relative path. */
+    toPath(path) {
+        const url = this.#appendQs(path);
+        this.#response.status(this.#status);
+        this.#response.header('location', url);
+        this.#response.setBody('');
+    }
+    /** Redirect to a named route. */
+    toRoute(name, params) {
+        if (!this.#routeUrlResolver) {
+            throw new Error('Route URL resolver not configured. Cannot redirect to named route.');
+        }
+        const path = this.#routeUrlResolver(name, params);
+        this.toPath(path);
+    }
+    /** Redirect back to the previous page (Referer header). */
+    back(fallback = '/') {
+        const referer = this.#requestReferer ?? fallback;
+        this.toPath(referer);
+    }
+    #appendQs(path) {
+        let qs = '';
+        if (this.#qs) {
+            qs = new URLSearchParams(this.#qs).toString();
+        }
+        else if (this.#forwardQs && this.#requestUrl) {
+            const qsIdx = this.#requestUrl.indexOf('?');
+            if (qsIdx !== -1)
+                qs = this.#requestUrl.slice(qsIdx + 1);
+        }
+        if (!qs)
+            return path;
+        return path.includes('?') ? `${path}&${qs}` : `${path}?${qs}`;
+    }
+}
+//# sourceMappingURL=RedirectBuilder.js.map

package/dist/http/RedirectBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedirectBuilder.js","sourceRoot":"","sources":["../../src/http/RedirectBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,OAAO,eAAe;IAC1B,SAAS,CAAU;IACnB,OAAO,GAAG,GAAG,CAAA;IACb,GAAG,GAAkC,IAAI,CAAA;IACzC,UAAU,GAAG,KAAK,CAAA;IAClB,WAAW,CAAS;IACpB,eAAe,CAAS;IACxB,iBAAiB,CAAmB;IAEpC,YACE,QAAkB,EAClB,OAIC;QAED,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,UAAU,CAAA;QACtC,IAAI,CAAC,eAAe,GAAG,OAAO,EAAE,cAAc,CAAA;QAC9C,IAAI,CAAC,iBAAiB,GAAG,OAAO,EAAE,gBAAgB,CAAA;IACpD,CAAC;IAED,gCAAgC;IAChC,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,2DAA2D;IAC3D,MAAM,CAAC,EAA2B;QAChC,IAAI,EAAE,EAAE,CAAC;YACP,IAAI,CAAC,GAAG,GAAG,EAAE,CAAA;QACf,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,UAAU,GAAG,IAAI,CAAA;QACxB,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,gDAAgD;IAChD,MAAM,CAAC,IAAY;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QAChC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,CAAA;QACtC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC5B,CAAC;IAED,iCAAiC;IACjC,OAAO,CAAC,IAAY,EAAE,MAA+B;QACnD,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAA;QACvF,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACjD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACnB,CAAC;IAED,2DAA2D;IAC3D,IAAI,CAAC,QAAQ,GAAG,GAAG;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,IAAI,QAAQ,CAAA;QAChD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACtB,CAAC;IAED,SAAS,CAAC,IAAY;QACpB,IAAI,EAAE,GAAG,EAAE,CAAA;QACX,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,EAAE,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC/C,CAAC;aAAM,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;YAC3C,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;QAC1D,CAAC;QACD,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAA;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAA;IAC/D,CAAC;CACF"}

package/dist/http/Request.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Request — wraps raw HTTP request data from the NAPI layer.
+ *
+ * Provides a fluent, AdonisJS-compatible API for reading request data.
+ * JSON body parsing is lazy — deferred until first access via input()/all()/body().
+ *
+ * @implements FR21
+ */
+import type { Dict } from '../types/helpers.js';
+export interface RawRequest {
+    method: string;
+    path: string;
+    query: string;
+    headers: Dict;
+    body: string;
+    bodyEncoding?: 'utf8' | 'base64';
+    /** Socket-level peer address (filled by the HTTP server). */
+    remoteAddr?: string;
+    /**
+     * Resolved client IP — pre-computed by the Rust-side HyperServer using the
+     * configured trusted-proxy CIDR list. JS reads this field directly; CIDR
+     * matching no longer happens in TS. When absent (mock/test fixtures) the
+     * `ip()` accessor falls back to legacy header parsing.
+     */
+    ip?: string;
+    /**
+     * Pre-parsed `multipart/form-data` payload — the HyperServer parses bodies
+     * server-side via `multer` and ships fields/files in this typed shape.
+     * Files are base64-encoded so the payload stays JSON-safe.
+     */
+    multipart?: {
+        fields: Array<{
+            name: string;
+            value: string;
+        }>;
+        files: Array<{
+            fieldName: string;
+            clientName: string;
+            contentType: string;
+            size: number;
+            contentB64: string;
+        }>;
+    };
+    /**
+     * Pre-parsed `Cookie:` header — name → value map computed by the Rust
+     * cookie crate. JS reads via `request.cookie(name)`. When absent (test
+     * fixtures), the accessor falls back to inline header parsing.
+     */
+    cookies?: Dict;
+}
+export declare class Request {
+    #private;
+    /**
+     * CSRF token for this request (AdonisJS idiom: `request.csrfToken`). Seeded
+     * by the `@c9up/blackhole` middleware when CSRF is enabled; `undefined`
+     * otherwise. Also published to `ctx.store` for templating helpers.
+     */
+    csrfToken?: string;
+    constructor(raw: RawRequest, params?: Dict);
+    /** HTTP method (GET, POST, etc.). */
+    method(): string;
+    /** Request URL (path + query string). */
+    url(includeQs?: boolean): string;
+    /** Request path (without query string). */
+    path(): string;
+    /**
+     * Resolved client IP. The HyperServer computes this once per request from
+     * the socket peer + `X-Forwarded-For` / `X-Real-IP` headers, gated by the
+     * configured trusted-proxy CIDR list, and ships the resolved value on
+     * `request.ip`. JS reads that field as-is.
+     *
+     * When `#raw.ip` is missing — only happens in test fixtures that
+     * hand-build `RawRequest` without going through the Rust pipeline — fall
+     * back to the socket peer (`remoteAddr`). Do NOT consult `X-Forwarded-For`
+     * or `X-Real-IP` here: those headers are attacker-controlled on direct
+     * requests and the trusted-proxy gate lives in Rust. Honouring them in
+     * the TS fallback would let test fixtures masking real spoofing
+     * regressions (two semantics for the same API). Fixtures that need to
+     * simulate a proxy-resolved IP must set `#raw.ip` directly to the
+     * desired resolved value.
+     */
+    ip(): string;
+    /**
+     * Return all cookies sent on this request as a name → value map. The
+     * HyperServer parses the `Cookie:` header once via the `cookie` crate
+     * (RFC 6265) and ships the result on `RawRequest.cookies`. Test fixtures
+     * that don't pre-fill the field fall back to inline parsing of the raw
+     * header — same tolerant `;`-split with quoted-value passthrough.
+     */
+    cookies(): Dict;
+    /** Pre-parsed cookie value by name, or `null` when absent. */
+    cookie(name: string): string | null;
+    /** Get the raw body as a string (decoded from base64 if binary). */
+    raw(): string;
+    /** Get the raw body as a Buffer (preserves binary integrity for file uploads). */
+    rawBuffer(): Buffer;
+    /** Get a single request header (case-insensitive). */
+    header(key: string): string | undefined;
+    /** Get all request headers. */
+    headers(): Readonly<Dict>;
+    /** Get a single route parameter. */
+    param(key: string, defaultValue?: string): string | undefined;
+    /** Get all route parameters. */
+    params(): Readonly<Dict>;
+    /** Get parsed query string as an object. */
+    qs(): Dict<unknown>;
+    /** Get the parsed request body. */
+    body(): unknown;
+    /** Get a single input value from body or query string. */
+    input<T = unknown>(key: string, defaultValue?: T): T;
+    /** Get all input (query string merged with body). */
+    all(): Dict<unknown>;
+    /** Cherry-pick specific keys from input. */
+    only<K extends string>(keys: K[]): Partial<Record<K, unknown>>;
+    /** Get all input except specific keys. */
+    except(keys: string[]): Dict<unknown>;
+    /** Check if the request content-type matches any of the given types. */
+    is(types: string[]): string | null;
+    /**
+     * Content negotiation — which of the offered types does the client accept,
+     * honouring RFC 7231 §5.3.2 quality values?
+     *
+     * Walks the parsed Accept header in descending q-order and returns the
+     * first server-offered type that matches. The server's preference order
+     * (`types` argument) is the tiebreaker only when multiple client entries
+     * share the same q. A bare `accepts(types)` therefore respects the
+     * client's stated priorities (`application/json;q=0.9, text/html;q=0.1`
+     * beats a server passing `['html', 'json']`).
+     *
+     * Aliases (`'json'` ↔ `application/json`, `'html'` ↔ `text/html`,
+     * `'xml'` ↔ any subtype containing `xml`) are honoured.
+     */
+    accepts(types: string[]): string | null;
+    /**
+     * Language negotiation from Accept-Language honouring RFC 4647 / 7231
+     * quality values. Returns the first offered language whose tag (or its
+     * primary subtag) matches the highest-q client entry, falling back to
+     * `langs[0]` when nothing matches and the client header is empty/absent.
+     */
+    language(langs: string[]): string | null;
+    /** Get an uploaded file by field name. */
+    file(fieldName: string, options?: import('../bodyparser/MultipartFile.js').FileValidationOptions): import('../bodyparser/MultipartFile.js').MultipartFile | null;
+    /** Get all uploaded files for a field name. */
+    files(fieldName: string, options?: import('../bodyparser/MultipartFile.js').FileValidationOptions): import('../bodyparser/MultipartFile.js').MultipartFile[];
+    /** Get all uploaded files. */
+    allFiles(): Map<string, import('../bodyparser/MultipartFile.js').MultipartFile[]>;
+    /**
+     * Pre-parsed `multipart/form-data` payload as the HyperServer wrote it.
+     * Returns `undefined` when the request wasn't multipart (or the test
+     * fixture didn't fill the field). BodyParser hydrates `MultipartFile`
+     * instances from this — application code should keep using
+     * `request.file()` / `request.files()`.
+     */
+    multipart(): NonNullable<RawRequest['multipart']> | undefined;
+    /** @internal Set files (called by BodyParser middleware). */
+    setFiles(files: import('../bodyparser/MultipartFile.js').MultipartFile[]): void;
+    /** @internal Set the parsed body (called by BodyParser middleware). */
+    setParsedBody(body: Dict<unknown>): void;
+}
+//# sourceMappingURL=Request.d.ts.map

package/dist/http/Request.d.ts.map

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