@fastang/core 0.1.0-alpha.0 → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.0-alpha.2
+
+- Accept native Fastify per-route options in API and contract helpers, including typed hooks, body limits, route config and HEAD behavior. File routing and shared contract schemas remain authoritative.
+
+- Add read-only `fastang routes` inspection with page/layout/metadata ancestry and explicit API methods, including versioned JSON output.
+
+- Validate FastAng configuration before starting the development server, using the same loader and checks as production builds.
+
+- Optional TypeBox API contracts infer Fastify handler types and Angular JSON client requests and successful responses.
+- Shared contracts reuse runtime schemas, check file-route consistency and encode API URLs explicitly.
+
+## 0.1.0-alpha.1
+
+- Preserve separate Set-Cookie headers and allow explicit per-dispatch forwarding to HTML responses.
+- Keep inherited credentials out of Angular's default HTTP transfer cache.
+- Treat internal API redirects as HttpClient errors and normalize local dispatch paths.
+- Reject Set-Cookie responses during public prerendering.
+
+- Validate prerender and Vercel configuration before changing build output, including plain config exports.
+- Reject unknown options, invalid types, reserved paths and conflicting prerender destinations.
+
 ## 0.1.0-alpha.0
 
 Initial experimental release.

package/README.md

@@ -1,7 +1,7 @@
 # @fastang/core
 
 Experimental FastAng runtime and tooling for Angular + Fastify applications.
-Version 0.1.0-alpha.0 is an experimental alpha. Public APIs may change between alpha releases.
+Version 0.1.0-alpha.2 is an experimental alpha. Public APIs may change between alpha releases.
 
 The package contains compiled JavaScript and TypeScript declarations. Angular,
 Fastify, Vite and the Angular compiler are explicit peer dependencies so the app
@@ -25,6 +25,7 @@ Registry installation is available once both alpha packages have been published.
 - `@fastang/core/angular`: `createRenderer(RootComponent, createAppConfig)` with per-request providers, HTTP transfer cache and router redirects.
 - `@fastang/core/vite`: `defineFastangConfig()` for Angular compilation, generated routes and server/client boundaries.
 - `@fastang/core/config`, `/api`, `/server`, `/http-server`, `/node-handler`, `/listen`, `/render-context`: focused imports.
+- `/contracts`, `/contract-route`, `/http-client`: optional shared TypeBox contracts, Fastify registration and Angular JSON requests (from `0.1.0-alpha.2`). Install `@sinclair/typebox` to use contracts.
 - `/routes`, `/adapters/vercel`, `/adapters/vercel-plan`, `/vite-plugin`: lower-level tooling APIs; still experimental.
 
 `createServer()` and `createApiServer()` accept a `registerApi(app)` callback.
@@ -52,3 +53,26 @@ npm pack --workspace @fastang/core --pack-destination /tmp
 
 Install the tarball into a copy of `examples/starter`. No global CLI, repository
 source files or website assets are required by the installed package.
+
+## Inspect file routes
+
+From `0.1.0-alpha.2`, `fastang routes` lists page paths in matching order with their source
+files, ancestor layouts and metadata files, followed by explicit API methods.
+Use `fastang routes --json` for a JSON document with `schemaVersion: 1`, `pages`
+and `api` arrays.
+
+Inspection uses the same discovery and collision checks as generation. It does
+not import application modules, evaluate configuration, write generated files,
+build the app or start a server. Paths describe file conventions: custom Angular
+router prefixes, routes registered by plugins and Fastify's implicit HEAD routes
+are not included. `**` denotes an Angular catch-all; API catch-alls use `*`.
+The output does not report prerendering or deployment-function assignment.
+
+## Native API route options
+
+From `0.1.0-alpha.2`, `defineApiRoute()` forwards native Fastify route options, including hooks,
+`bodyLimit`, `config`, `exposeHeadRoute` and route error handlers. Method and URL
+remain controlled by file routing. Hooks preserve the request/reply generic types;
+a second generic describes custom route config. Schemas are optional, as in
+Fastify. `defineContractRoute()` from `/contract-route` accepts the same options,
+except that its schema comes from the shared contract.

package/dist/adapters/vercel-plan.d.ts

@@ -1,4 +1,4 @@
-import type { VercelOptions } from '../config.ts';
+import { type VercelOptions } from '../config.ts';
 import { type FileRoute } from '../routes.ts';
 export interface FunctionPlan {
     name: string;

package/dist/adapters/vercel-plan.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { validateVercelOptions } from "../config.js";
 import { discover, discoverPageTree, pageRoutesSource, renderedPageFiles } from "../routes.js";
 export const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 /** Match an entire route; parameter segments never consume a slash. */
@@ -15,15 +16,9 @@ function identifier(path) {
     return slug + '-' + createHash('sha256').update(normalized).digest('hex').slice(0, 12);
 }
 export function planVercelFunctions(pages, apis, prerendered, options = {}) {
+    validateVercelOptions(options);
     const mode = options.functions ?? 'shared';
-    if (mode !== 'shared' && mode !== 'routes')
-        throw new Error('vercel.functions must be shared or routes');
     const prefixes = [...new Set(options.pagePrefixes ?? [''])];
-    if (!prefixes.length || prefixes.some((prefix) => prefix !== '' && !/^\/(?:[\w-]+)(?:\/[\w-]+)*$/.test(prefix))) {
-        throw new Error('vercel.pagePrefixes must contain empty or absolute static prefixes without a trailing slash');
-    }
-    if (prefixes.some((prefix) => /^\/(?:api|assets|__fastang)(?:\/|$)/.test(prefix)))
-        throw new Error('Reserved Vercel page prefix');
     const functions = [
         { name: mode === 'routes' ? '__fastang/ssr' : 'ssr', kind: 'ssr', entry: 'vercel', paths: [], sources: [] },
         { name: mode === 'routes' ? '__fastang/api' : 'api', kind: 'api', entry: 'api', paths: [], sources: [] },

package/dist/angular.js

@@ -19,8 +19,12 @@ function localApiBackend() {
             if (contentType && !request.headers.has('content-type'))
                 headers['content-type'] = contentType;
             return from(context.dispatchApi(target.pathname + target.search, request.method, request.body, headers)).pipe(map((response) => {
-                const responseHeaders = new HttpHeaders(response.headers);
-                if (response.status >= 400)
+                let responseHeaders = new HttpHeaders(response.headers);
+                // Inherited credentials were invisible to the transfer-cache request check.
+                // Mark the response private so Angular's native response check excludes it.
+                if (response.credentialed)
+                    responseHeaders = responseHeaders.set('cache-control', 'private, no-store');
+                if (response.status < 200 || response.status >= 300)
                     throw new HttpErrorResponse({ status: response.status, error: response.body, headers: responseHeaders, url: request.url });
                 return new HttpResponse({ status: response.status, body: response.body, headers: responseHeaders, url: request.url });
             }));

package/dist/api.d.ts

@@ -1,7 +1,7 @@
-import type { FastifyInstance, FastifySchema, HTTPMethods, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault, RouteGenericInterface, RouteHandlerMethod } from 'fastify';
-type Handler<T extends RouteGenericInterface> = RouteHandlerMethod<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, T>;
-export declare function defineApiRoute<T extends RouteGenericInterface>(options: {
-    schema: FastifySchema;
-    handler: Handler<T>;
-}): (app: FastifyInstance, method: HTTPMethods, url: string) => void;
-export {};
+import type { FastifyInstance, HTTPMethods, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault, RouteGenericInterface, RouteOptions } from 'fastify';
+/** Native Fastify route options; the file convention owns method and URL. */
+export type ApiRouteOptions<T extends RouteGenericInterface = RouteGenericInterface, ContextConfig = Record<string, unknown>> = Omit<RouteOptions<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, T, ContextConfig>, 'method' | 'url'> & {
+    method?: never;
+    url?: never;
+};
+export declare function defineApiRoute<T extends RouteGenericInterface, ContextConfig = Record<string, unknown>>(options: ApiRouteOptions<T, ContextConfig>): (app: FastifyInstance, method: HTTPMethods, url: string) => void;

package/dist/api.js

@@ -1,4 +1,3 @@
-// I tipi rimangono nel closure: nessun cast quando si registra la rotta generata.
 export function defineApiRoute(options) {
     return (app, method, url) => { app.route({ ...options, method, url }); };
 }

package/dist/cli.js

@@ -3,12 +3,14 @@ const command = process.argv[2];
 try {
     if (command === 'generate')
         await (await import("./routes.js")).generate();
+    else if (command === 'routes')
+        await import("./commands/inspect-routes.js");
     else if (command === 'dev')
         await import("./commands/dev.js");
     else if (command === 'build')
         await import("./commands/build.js");
     else if (!command || command === '--help' || command === '-h')
-        console.log('Usage: fastang <dev|generate|build> [--vercel]');
+        console.log('Usage: fastang <dev|generate|build|routes>\n  build [--vercel]\n  routes [--json]');
     else
         throw new Error(`Unknown command: ${command}`);
 }

package/dist/commands/build.js

@@ -10,25 +10,16 @@ import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { build } from 'vite';
-import { loadConfigFromFile } from 'vite';
 import { prepareVercelPlan } from "../adapters/vercel-plan.js";
 import { buildVercelOutput } from "../adapters/vercel.js";
-import { staticFile } from "../server.js";
-const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, 'fastang.config.ts');
-if (!loaded)
-    throw new Error('Missing fastang.config.ts');
-const config = loaded.config;
+import { staticFile } from "../static-path.js";
+import { loadFastangConfig } from "./load-config.js";
+const config = await loadFastangConfig('build');
 const vercel = process.argv.includes('--vercel');
-await rm('dist', { recursive: true, force: true });
 const paths = [...new Set(config.prerender)];
-for (const path of paths) {
-    staticFile(path);
-    if (path === '/' || path === '/api' || path.startsWith('/api/') || path.startsWith('/assets/')) {
-        throw new Error(`Percorso riservato al runtime: ${path}`);
-    }
-}
 const vercelPlan = vercel ? await prepareVercelPlan(paths, config.vercel) : undefined;
 const endpointEntries = Object.fromEntries((vercelPlan?.functions ?? []).filter((fn) => fn.entry.startsWith('endpoint-')).map((fn) => [fn.entry, `.fastang/vercel/${fn.entry}.ts`]));
+await rm('dist', { recursive: true, force: true });
 await build({ build: { outDir: 'dist/client' } });
 await build({ build: {
         outDir: 'dist/server', minify: true, ssr: vercel ? true : 'src/server/start.ts',
@@ -57,6 +48,8 @@ try {
         const response = await app.inject({ url: path });
         if (response.statusCode !== 200)
             throw new Error(`Prerender ${path}: HTTP ${response.statusCode}`);
+        if (response.headers['set-cookie'])
+            throw new Error(`Prerender ${path}: Set-Cookie is not allowed in public HTML`);
         const target = resolve('dist/client', staticFile(path));
         await mkdir(dirname(target), { recursive: true });
         await writeFile(target, response.body);

package/dist/commands/dev-server.js

@@ -6,6 +6,8 @@ import { listen } from "../listen.js";
 import { tsImport } from 'tsx/esm/api';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { loadFastangConfig } from "./load-config.js";
+await loadFastangConfig('serve');
 const { configureServer } = await tsImport(pathToFileURL(resolve('src/server/plugins.ts')).href, import.meta.url);
 const { registerApi } = await tsImport(pathToFileURL(resolve('.fastang/api.ts')).href, import.meta.url);
 let vite;

package/dist/commands/inspect-routes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/inspect-routes.js

@@ -0,0 +1,25 @@
+import { inspectRoutes } from "../routes.js";
+const args = process.argv.slice(3);
+if (args.length > 1 || args.some(argument => argument !== '--json'))
+    throw new Error('Usage: fastang routes [--json]');
+const manifest = await inspectRoutes();
+if (args.includes('--json'))
+    console.log(JSON.stringify(manifest, null, 2));
+else {
+    console.log('File-based page routes (matching order)');
+    for (const page of manifest.pages) {
+        console.log(`PAGE ${page.path}  ${page.file}`);
+        for (const layout of page.layouts)
+            console.log(`  layout ${layout.path}  ${layout.file}${layout.metadata ? `  metadata: ${layout.metadata}` : ''}`);
+        if (page.metadata)
+            console.log(`  metadata ${page.metadata}`);
+    }
+    if (!manifest.pages.length)
+        console.log('(none)');
+    console.log('\nFile-based API routes');
+    for (const route of manifest.api)
+        console.log(`${route.method.padEnd(7)} ${route.path}  ${route.file}`);
+    if (!manifest.api.length)
+        console.log('(none)');
+    console.log('\nFile conventions only: application router prefixes, plugin routes and implicit HEAD routes are not included.');
+}

package/dist/commands/load-config.d.ts

@@ -0,0 +1,3 @@
+import { type FastangConfig } from '../config.ts';
+/** Use the same loader and validation before initializing either server or build. */
+export declare function loadFastangConfig(command: 'serve' | 'build'): Promise<FastangConfig>;

package/dist/commands/load-config.js

@@ -0,0 +1,9 @@
+import { loadConfigFromFile } from 'vite';
+import { validateConfig } from "../config.js";
+/** Use the same loader and validation before initializing either server or build. */
+export async function loadFastangConfig(command) {
+    const loaded = await loadConfigFromFile({ command, mode: command === 'build' ? 'production' : 'development' }, 'fastang.config.ts');
+    if (!loaded)
+        throw new Error('Missing fastang.config.ts');
+    return validateConfig(loaded.config);
+}

package/dist/config.d.ts

@@ -11,3 +11,7 @@ export interface FastangConfig {
     vercel?: VercelOptions;
 }
 export declare function defineConfig(config: FastangConfig): FastangConfig;
+/** Also used by the adapter when invoked without defineConfig. */
+export declare function validateVercelOptions(value: unknown): asserts value is VercelOptions;
+/** Validate plain exports too, before the build touches existing output. */
+export declare function validateConfig(value: unknown): FastangConfig;

package/dist/config.js

@@ -1,3 +1,53 @@
+import { staticFile } from "./static-path.js";
 export function defineConfig(config) {
-    return config;
+    return validateConfig(config);
+}
+function object(value, field, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${field} must be an object`);
+    for (const key of Object.keys(value))
+        if (!keys.includes(key))
+            throw new Error(`Unknown ${field} option: ${key}`);
+}
+/** Also used by the adapter when invoked without defineConfig. */
+export function validateVercelOptions(value) {
+    object(value, 'vercel', ['functions', 'pagePrefixes', 'prunePages']);
+    if (value.functions !== undefined && value.functions !== 'shared' && value.functions !== 'routes')
+        throw new Error('vercel.functions must be shared or routes');
+    if (value.prunePages !== undefined && typeof value.prunePages !== 'boolean')
+        throw new Error('vercel.prunePages must be a boolean');
+    if (value.pagePrefixes !== undefined) {
+        if (!Array.isArray(value.pagePrefixes) || !value.pagePrefixes.length || value.pagePrefixes.some(prefix => typeof prefix !== 'string' || (prefix !== '' && !/^\/(?:[\w-]+)(?:\/[\w-]+)*$/.test(prefix)))) {
+            throw new Error('vercel.pagePrefixes must contain empty or absolute static prefixes without a trailing slash');
+        }
+        if (value.pagePrefixes.some(prefix => /^\/(?:api|assets|__fastang)(?:\/|$)/.test(prefix)))
+            throw new Error('Reserved Vercel page prefix');
+    }
+}
+/** Validate plain exports too, before the build touches existing output. */
+export function validateConfig(value) {
+    object(value, 'FastAng', ['prerender', 'vercel']);
+    if (!Array.isArray(value.prerender))
+        throw new Error('prerender must be an array of URL paths');
+    const targets = new Map();
+    for (const [index, path] of value.prerender.entries()) {
+        if (typeof path !== 'string')
+            throw new Error(`prerender[${index}] must be a URL path string`);
+        let target;
+        try {
+            target = staticFile(path);
+        }
+        catch {
+            throw new Error(`Invalid prerender[${index}] path: ${JSON.stringify(path)}`);
+        }
+        if (path === '/' || /^\/(?:api|assets|__fastang)(?:\/|$)/.test(path))
+            throw new Error(`Reserved prerender path: ${path}`);
+        const previous = targets.get(target);
+        if (previous !== undefined && previous !== path)
+            throw new Error(`Conflicting prerender paths: ${previous} and ${path}`);
+        targets.set(target, path);
+    }
+    if (value.vercel !== undefined)
+        validateVercelOptions(value.vercel);
+    return value;
 }

package/dist/contract-route.d.ts

@@ -0,0 +1,7 @@
+import type { FastifyInstance, HTTPMethods } from 'fastify';
+import type { ApiRouteOptions } from './api.ts';
+import type { ApiContract, ApiRouteTypes } from './contracts.ts';
+/** Infer handler types and reuse validation/serialization from the shared contract. */
+export declare function defineContractRoute<C extends ApiContract, ContextConfig = Record<string, unknown>>(contract: C, options: Omit<ApiRouteOptions<ApiRouteTypes<C>, ContextConfig>, 'schema'> & {
+    schema?: never;
+}): (app: FastifyInstance, method: HTTPMethods, url: string) => void;

package/dist/contract-route.js

@@ -0,0 +1,8 @@
+/** Infer handler types and reuse validation/serialization from the shared contract. */
+export function defineContractRoute(contract, options) {
+    return (app, method, url) => {
+        if (method !== contract.method || url !== contract.path)
+            throw new Error(`API contract mismatch: file route ${method} ${url}, contract ${contract.method} ${contract.path}`);
+        app.route({ ...options, method, url, schema: contract.schema });
+    };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,46 @@
+import type { Static, TSchema } from '@sinclair/typebox';
+export interface ApiSchemas {
+    params?: TSchema;
+    querystring?: TSchema;
+    body?: TSchema;
+    response: Record<number, TSchema>;
+}
+export interface ApiContract<S extends ApiSchemas = ApiSchemas> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    schema: S;
+}
+type Field<S, K extends PropertyKey> = S extends Record<K, infer T extends TSchema> ? Static<T> : never;
+type InputFields<C extends ApiContract> = (C['schema'] extends {
+    params: TSchema;
+} ? {
+    params: Field<C['schema'], 'params'>;
+} : {}) & (C['schema'] extends {
+    querystring: TSchema;
+} ? {
+    query: Field<C['schema'], 'querystring'>;
+} : {}) & (C['schema'] extends {
+    body: TSchema;
+} ? {
+    body: Field<C['schema'], 'body'>;
+} : {});
+export type ApiInput<C extends ApiContract> = keyof InputFields<C> extends never ? Record<string, never> : InputFields<C>;
+type UrlFields<C extends ApiContract> = Pick<InputFields<C>, Extract<keyof InputFields<C>, 'params' | 'query'>>;
+export type ApiUrlInput<C extends ApiContract> = keyof UrlFields<C> extends never ? Record<string, never> : UrlFields<C>;
+export type ApiReply<C extends ApiContract> = {
+    [K in keyof C['schema']['response']]: C['schema']['response'][K] extends TSchema ? Static<C['schema']['response'][K]> : never;
+};
+export type ApiSuccess<C extends ApiContract> = {
+    [K in keyof ApiReply<C>]: K extends string | number ? `${K}` extends `2${string}` ? ApiReply<C>[K] : never : never;
+}[keyof ApiReply<C>];
+export type ApiRouteTypes<C extends ApiContract> = {
+    Params: Field<C['schema'], 'params'>;
+    Querystring: Field<C['schema'], 'querystring'>;
+    Body: Field<C['schema'], 'body'>;
+    Reply: ApiReply<C>;
+};
+/** Public JSON schemas only: do not import a server handler into a contract module. */
+export declare function defineApiContract<const S extends ApiSchemas>(contract: ApiContract<S>): ApiContract<S>;
+/** Encodes scalar path values and flat query values; never stringifies objects. */
+export declare function apiUrl<C extends ApiContract>(contract: C, input: ApiUrlInput<C>): string;
+export {};

package/dist/contracts.js

@@ -0,0 +1,51 @@
+const pathPattern = /^\/api\/(?:[\w-]+|:[a-zA-Z_]\w*)(?:\/(?:[\w-]+|:[a-zA-Z_]\w*))*$/;
+/** Public JSON schemas only: do not import a server handler into a contract module. */
+export function defineApiContract(contract) {
+    if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(contract.method))
+        throw new Error('Unsupported contract method');
+    if (!pathPattern.test(contract.path))
+        throw new Error('Contract path must be a local /api/... path with static or named segments');
+    const parameters = contract.path.split('/').filter(part => part.startsWith(':')).map(part => part.slice(1));
+    const schema = contract.schema.params;
+    if (schema && schema.type !== 'object')
+        throw new Error('schema.params must be an object schema');
+    const properties = Object.keys(schema?.properties ?? {});
+    if (new Set(parameters).size !== parameters.length || parameters.length !== properties.length || parameters.some(name => !properties.includes(name) || !schema?.required?.includes(name))) {
+        throw new Error('Contract path parameters must match required schema.params properties');
+    }
+    if (contract.method === 'GET' && contract.schema.body)
+        throw new Error('GET contracts do not support bodies');
+    if (!Object.keys(contract.schema.response).some(status => /^2\d\d$/.test(status)) || Object.keys(contract.schema.response).some(status => !/^[1-5]\d\d$/.test(status)))
+        throw new Error('Contract response schemas need HTTP statuses and at least one 2xx response');
+    return contract;
+}
+/** Encodes scalar path values and flat query values; never stringifies objects. */
+export function apiUrl(contract, input) {
+    if (!pathPattern.test(contract.path))
+        throw new Error('Invalid local API contract path');
+    const values = input;
+    const names = contract.path.split('/').filter(part => part.startsWith(':')).map(part => part.slice(1));
+    if (Object.keys(values.params ?? {}).some(name => !names.includes(name)))
+        throw new Error('Unknown API path parameter');
+    const scalar = (value) => {
+        if (typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)))
+            return String(value);
+        throw new Error('API URL values must be strings, finite numbers or booleans');
+    };
+    const path = contract.path.split('/').map(part => {
+        if (!part.startsWith(':'))
+            return part;
+        const value = scalar(values.params?.[part.slice(1)]);
+        if (!value || value === '.' || value === '..')
+            throw new Error('Empty or dot path parameters are not supported');
+        return encodeURIComponent(value);
+    }).join('/');
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(values.query ?? {})) {
+        if (value === undefined)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value])
+            query.append(key, scalar(item));
+    }
+    return path + (query.size ? '?' + query.toString() : '');
+}

package/dist/http-client.d.ts

@@ -0,0 +1,28 @@
+import { HttpClient, type HttpContext, type HttpHeaders } from '@angular/common/http';
+import type { Observable } from 'rxjs';
+import { type ApiContract, type ApiInput, type ApiSuccess } from './contracts.ts';
+export interface ApiRequestOptions {
+    headers?: HttpHeaders | Record<string, string | string[]>;
+    context?: HttpContext;
+    withCredentials?: boolean;
+    credentials?: RequestCredentials;
+    transferCache?: boolean | {
+        includeHeaders?: string[];
+    };
+}
+type Arguments<C extends ApiContract> = C['schema'] extends {
+    params: unknown;
+} | {
+    querystring: unknown;
+} | {
+    body: unknown;
+} ? [input: ApiInput<C>, options?: ApiRequestOptions] : [input?: ApiInput<C>, options?: ApiRequestOptions];
+/** Thin JSON client: native HttpClient interceptors, errors and transfer cache apply. */
+export declare function createApiClient(http: HttpClient): {
+    request<C extends ApiContract>(contract: C, ...args: Arguments<C>): Observable<ApiSuccess<C>>;
+};
+/** Call in an Angular injection context, just like inject(HttpClient). */
+export declare function injectApiClient(): {
+    request<C extends ApiContract>(contract: C, ...args: Arguments<C>): Observable<ApiSuccess<C>>;
+};
+export {};

package/dist/http-client.js

@@ -0,0 +1,16 @@
+import { inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { apiUrl } from "./contracts.js";
+/** Thin JSON client: native HttpClient interceptors, errors and transfer cache apply. */
+export function createApiClient(http) {
+    return {
+        request(contract, ...args) {
+            const [input = {}, options = {}] = args;
+            return http.request(contract.method, apiUrl(contract, input), {
+                ...options, body: input.body, observe: 'body', responseType: 'json',
+            });
+        },
+    };
+}
+/** Call in an Angular injection context, just like inject(HttpClient). */
+export function injectApiClient() { return createApiClient(inject(HttpClient)); }

package/dist/render-context.d.ts

@@ -1,7 +1,14 @@
 export interface ApiDispatchResult {
     status: number;
     body: unknown;
-    headers: Record<string, string>;
+    /** Set-Cookie values remain separate, including Expires commas. */
+    headers: Record<string, string | string[]>;
+    /** Credentials actually sent to the internal endpoint, including inherited ones. */
+    credentialed: boolean;
+}
+export interface ApiDispatchOptions {
+    /** Append internal Set-Cookie headers to this HTML response only. Default: false. */
+    forwardSetCookie?: boolean;
 }
 export interface RenderContext {
     status: number;
@@ -9,5 +16,5 @@ export interface RenderContext {
         location: string;
         status?: 301 | 302 | 303 | 307 | 308;
     };
-    dispatchApi(path: string, method: string, body: unknown, headers: Record<string, string>): Promise<ApiDispatchResult>;
+    dispatchApi(path: string, method: string, body: unknown, headers: Record<string, string>, options?: ApiDispatchOptions): Promise<ApiDispatchResult>;
 }

package/dist/routes.d.ts

@@ -16,6 +16,26 @@ export interface PageRouteNode {
 }
 export declare function buildPageTree(files: string[]): PageRouteNode[];
 export declare function discoverPageTree(directory: string): Promise<PageRouteNode[]>;
+export interface RouteInspection {
+    schemaVersion: 1;
+    pages: {
+        path: string;
+        file: string;
+        metadata?: string;
+        layouts: {
+            path: string;
+            file: string;
+            metadata?: string;
+        }[];
+    }[];
+    api: {
+        method: string;
+        path: string;
+        file: string;
+    }[];
+}
+/** Inspect file conventions without evaluating application modules or writing files. */
+export declare function inspectRoutes(root?: string): Promise<RouteInspection>;
 export interface PageRoutesSourceOptions {
     pagesImport: string;
     selectedFile?: string;

package/dist/routes.js

@@ -177,6 +177,33 @@ export function buildPageTree(files) {
 export async function discoverPageTree(directory) {
     return buildPageTree(await listFiles(directory));
 }
+/** Inspect file conventions without evaluating application modules or writing files. */
+export async function inspectRoutes(root = process.cwd()) {
+    const [tree, endpoints] = await Promise.all([
+        discoverPageTree(resolve(root, 'src/app/pages')),
+        discover(resolve(root, 'src/server/api'), 'api'),
+    ]);
+    const pages = [];
+    const describe = (node) => ({
+        path: '/' + node.fullPath,
+        file: 'src/app/pages/' + node.file,
+        ...(node.metadata ? { metadata: 'src/app/pages/' + node.metadata } : {}),
+    });
+    function visit(nodes, layouts) {
+        for (const node of nodes) {
+            if (node.kind === 'layout')
+                visit(node.children ?? [], [...layouts, describe(node)]);
+            else
+                pages.push({ ...describe(node), layouts });
+        }
+    }
+    visit(tree, []);
+    return {
+        schemaVersion: 1,
+        pages,
+        api: endpoints.map(route => ({ method: route.method, path: '/api' + (route.path ? '/' + route.path : ''), file: 'src/server/api/' + route.file })),
+    };
+}
 async function writeChanged(file, content) {
     await mkdir(dirname(file), { recursive: true });
     if (await readFile(file, 'utf8').catch(() => '') !== content)

package/dist/server.d.ts

@@ -1,3 +1,4 @@
+export { staticFile } from './static-path.ts';
 import { type FastifyInstance, type FastifyServerOptions } from 'fastify';
 import type { RenderContext } from './render-context.ts';
 export type Renderer = (url: string, document: string, context: RenderContext) => Promise<string>;
@@ -10,6 +11,5 @@ export interface ServerOptions {
     prerendered?: string[];
     configure?: (app: FastifyInstance) => Promise<void> | void;
 }
-export declare function staticFile(path: string): string;
 export declare function createApiServer(options?: Pick<ServerOptions, 'logger' | 'configure' | 'registerApi'>): Promise<FastifyInstance>;
 export declare function createServer(options: ServerOptions): Promise<FastifyInstance>;

package/dist/server.js

@@ -1,14 +1,10 @@
+import { staticFile } from "./static-path.js";
+export { staticFile } from "./static-path.js";
 import { createHttpServer } from "./http-server.js";
 import {} from 'fastify';
 import { readFile } from 'node:fs/promises';
 import { extname, resolve } from 'node:path';
 import { normalizeRedirectLocation } from "./redirect.js";
-export function staticFile(path) {
-    if (!path.startsWith('/') || path.includes('//') || !/^\/[a-zA-Z0-9_/-]*$/.test(path) || path.split('/').includes('..')) {
-        throw new Error(`Percorso di prerendering non supportato: ${path}`);
-    }
-    return `${path.replace(/^\/|\/$/g, '')}${path === '/' ? '' : '/'}index.html`;
-}
 export async function createApiServer(options = {}) {
     return createHttpServer({
         ...options,
@@ -42,9 +38,11 @@ export async function createServer(options) {
                 const html = await readFile(resolve(options.clientDir, staticPath), 'utf8');
                 return reply.header('x-fastang-render', 'prerender').header('cache-control', 'public, max-age=0, must-revalidate').type('text/html; charset=utf-8').send(html);
             }
+            const responseCookies = [];
             const context = {
                 status: 200,
-                async dispatchApi(path, method, body, headers) {
+                async dispatchApi(path, method, body, headers, dispatchOptions = {}) {
+                    path = normalizeRedirectLocation(path);
                     if (!path.startsWith('/api/'))
                         throw new Error('Solo API locali consentite');
                     const forwarded = {};
@@ -53,18 +51,24 @@ export async function createServer(options) {
                         if (typeof value === 'string')
                             forwarded[name] = value;
                     }
+                    const outgoing = { ...forwarded, ...(body == null ? {} : { 'content-type': 'application/json' }), ...Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value])) };
                     const response = await app.inject({
                         method: method, url: path,
-                        headers: { ...forwarded, ...(body == null ? {} : { 'content-type': 'application/json' }), ...headers },
+                        headers: outgoing,
                         ...(body == null ? {} : { payload: typeof body === 'string' ? body : JSON.stringify(body) }),
                     });
                     const responseHeaders = {};
                     for (const [name, value] of Object.entries(response.headers)) {
                         if (value !== undefined)
-                            responseHeaders[name] = Array.isArray(value) ? value.join(', ') : String(value);
+                            responseHeaders[name] = Array.isArray(value) ? [...value] : String(value);
+                    }
+                    if (dispatchOptions.forwardSetCookie === true) {
+                        const cookies = responseHeaders['set-cookie'];
+                        if (cookies)
+                            responseCookies.push(...(Array.isArray(cookies) ? cookies : [cookies]));
                     }
                     const contentType = String(response.headers['content-type'] ?? '');
-                    return { status: response.statusCode, body: contentType.includes('json') ? response.json() : response.body, headers: responseHeaders };
+                    return { status: response.statusCode, body: contentType.includes('json') ? response.json() : response.body, headers: responseHeaders, credentialed: !!(outgoing['cookie'] || outgoing['authorization']) };
                 },
             };
             const html = await options.render(`http://fastang.local${request.url}`, await options.template(request.url), context);
@@ -72,9 +76,14 @@ export async function createServer(options) {
                 const status = context.redirect.status ?? 302;
                 if (![301, 302, 303, 307, 308].includes(status))
                     throw new Error('Stato redirect non valido');
+                const location = normalizeRedirectLocation(context.redirect.location);
+                if (responseCookies.length)
+                    reply.header('set-cookie', responseCookies);
                 return reply.header('x-fastang-render', 'redirect').header('cache-control', 'private, no-store')
-                    .redirect(normalizeRedirectLocation(context.redirect.location), status);
+                    .redirect(location, status);
             }
+            if (responseCookies.length)
+                reply.header('set-cookie', responseCookies);
             return reply.code(context.status).header('x-fastang-render', 'ssr').header('cache-control', 'private, no-store').type('text/html; charset=utf-8').send(html);
         });
         return app;

package/dist/static-path.d.ts

@@ -0,0 +1 @@
+export declare function staticFile(path: string): string;

package/dist/static-path.js

@@ -0,0 +1,6 @@
+export function staticFile(path) {
+    if (!path.startsWith('/') || path.includes('//') || !/^\/[a-zA-Z0-9_/-]*$/.test(path) || path.split('/').includes('..')) {
+        throw new Error(`Percorso di prerendering non supportato: ${path}`);
+    }
+    return `${path.replace(/^\/|\/$/g, '')}${path === '/' ? '' : '/'}index.html`;
+}

package/dist/vite-plugin.js

@@ -3,7 +3,7 @@ export function isServerModule(id) {
     const path = id.replaceAll('\\', '/').split('?')[0];
     return /\/(src\/server|framework|\.fastang)\//.test(path)
         || /\.server\.[cm]?[jt]s$/.test(path)
-        || /\/(?:@fastang\/core|packages\/core)\/(?:src|dist)\/(?:index|server|http-server|node-handler|listen|angular|api|routes|vite|vite-plugin|cli|commands\/.*|adapters\/.*)\.[cm]?[jt]s$/.test(path);
+        || /\/(?:@fastang\/core|packages\/core)\/(?:src|dist)\/(?:index|server|http-server|node-handler|listen|angular|api|contract-route|routes|vite|vite-plugin|cli|commands\/.*|adapters\/.*)\.[cm]?[jt]s$/.test(path);
 }
 export function fastang() {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastang/core",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "description": "Angular rendering, Fastify APIs and file-based routing.",
   "license": "MIT",
@@ -78,6 +78,18 @@
     "./vite": {
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./contract-route": {
+      "types": "./dist/contract-route.d.ts",
+      "import": "./dist/contract-route.js"
+    },
+    "./http-client": {
+      "types": "./dist/http-client.d.ts",
+      "import": "./dist/http-client.js"
     }
   },
   "scripts": {
@@ -104,7 +116,8 @@
     "vite": "8.3.4",
     "typescript": "~6.0.2",
     "@angular/compiler-cli": "22.2.3",
-    "@angular/build": "22.2.3"
+    "@angular/build": "22.2.3",
+    "@sinclair/typebox": "^0.34.41"
   },
   "repository": {
     "type": "git",
@@ -119,5 +132,10 @@
   "homepage": "https://fastang.dev",
   "bugs": {
     "url": "https://github.com/daclab-dev/fastang/issues"
+  },
+  "peerDependenciesMeta": {
+    "@sinclair/typebox": {
+      "optional": true
+    }
   }
 }