@tmlmobilidade/go-clients-fastify 20260828.1636.54

package/dist/authorization-middleware.d.ts

@@ -0,0 +1,25 @@
+import { FastifyReply, type FastifyRequest } from './fastify-service.js';
+import { type Organization, type User } from '@tmlmobilidade/go-types-core';
+import { type ActionsOf, type Permission } from '@tmlmobilidade/go-types-permissions';
+interface AuthorizationPermissionCheck<S extends Permission['scope'] = Permission['scope']> {
+    actions: ActionsOf<S>[];
+    requireAll?: boolean;
+    scope: S;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        me: User;
+        organization: Organization;
+        permissions: Permission[];
+    }
+}
+/**
+ * Creates an authorization middleware that validates user authentication and permissions.
+ * @param scope The permission scope to check (optional).
+ * @param action The permission action(s) to check (optional).
+ * @param requireAll Whether all actions must be true or at least one must be true.
+ * @returns Fastify middleware function.
+ */
+export declare function authorizationMiddleware(checks: AuthorizationPermissionCheck[]): (request: FastifyRequest, reply: FastifyReply<string>) => Promise<void>;
+export declare function authorizationMiddleware<S extends Permission['scope']>(scope?: S, actions?: ActionsOf<S>[], requireAll?: boolean): (request: FastifyRequest, reply: FastifyReply<string>) => Promise<void>;
+export {};

package/dist/authorization-middleware.js

@@ -0,0 +1,66 @@
+/* * */
+import { HTTP_STATUS, HttpException } from '@tmlmobilidade/consts';
+import { AUTH_SESSION_COOKIE_NAME, authProvider } from '@tmlmobilidade/go-providers-auth';
+import { PermissionCatalog } from '@tmlmobilidade/go-types-permissions';
+function isPermissionCheckAllowed(permissionEntries, check) {
+    const permissionChecks = check.actions.map(action => PermissionCatalog.hasPermission(permissionEntries, check.scope, action));
+    return check.requireAll
+        ? permissionChecks.every(Boolean)
+        : permissionChecks.some(Boolean);
+}
+export function authorizationMiddleware(scopeOrChecks, actions = [], requireAll = false) {
+    return async (request, reply) => {
+        //
+        //
+        // Extract the session token from request cookies
+        const sessionToken = request.cookies.session_token;
+        if (!sessionToken) {
+            return reply
+                .setCookie(AUTH_SESSION_COOKIE_NAME, '', { httpOnly: true, maxAge: 0, path: '/', sameSite: 'lax', secure: true })
+                .send({ data: null, error: 'Session token is missing', statusCode: HTTP_STATUS.UNAUTHORIZED });
+        }
+        //
+        // Get user and permissions from cache or auth provider.
+        // Cache is per session token, and valid for 5 minutes.
+        // This reduces the number of calls to the auth provider.
+        try {
+            const userData = await authProvider.getUserFromSessionToken(sessionToken);
+            const permissionsData = await authProvider.getPermissionsFromSessionToken(sessionToken);
+            const organizationData = await authProvider.getOrganizationFromSessionToken(sessionToken);
+            if (!userData || !permissionsData || !organizationData) {
+                return reply
+                    .setCookie(AUTH_SESSION_COOKIE_NAME, '', { httpOnly: true, maxAge: 0, path: '/', sameSite: 'lax', secure: true })
+                    .send({ data: null, error: 'User, Permissions or Organization not found', statusCode: HTTP_STATUS.UNAUTHORIZED });
+            }
+            request.me = userData;
+            request.permissions = permissionsData;
+            request.organization = organizationData;
+        }
+        catch (error) {
+            console.error('Authorization Middleware Error:', error);
+            return reply
+                .setCookie(AUTH_SESSION_COOKIE_NAME, '', { httpOnly: true, maxAge: 0, path: '/', sameSite: 'lax', secure: true })
+                .send({ data: null, error: 'Authorization Middleware Error', statusCode: HTTP_STATUS.UNAUTHORIZED });
+        }
+        //
+        // Evaluate the retrieved permissions,
+        // if scope and actions are provided.
+        if (Array.isArray(scopeOrChecks)) {
+            const isAllowed = scopeOrChecks.some(check => isPermissionCheckAllowed(request.permissions, check));
+            if (!isAllowed) {
+                throw new HttpException(HTTP_STATUS.FORBIDDEN, `Insufficient permissions | User: ${request.me._id}`);
+            }
+            return;
+        }
+        if (!scopeOrChecks)
+            return;
+        const permissionChecks = actions.map(action => PermissionCatalog.hasPermission(request.permissions, scopeOrChecks, action));
+        const isAllowed = requireAll
+            ? permissionChecks.every(Boolean) // all must be true
+            : permissionChecks.some(Boolean); // at least one must be true
+        if (!isAllowed) {
+            throw new HttpException(HTTP_STATUS.FORBIDDEN, `Insufficient permissions | User: ${request.me._id} | Scope: "${scopeOrChecks}" | Actions: [${actions.join(',')}]`);
+        }
+        //
+    };
+}

package/dist/fastify-service.d.ts

@@ -0,0 +1,90 @@
+import '@fastify/cors';
+import '@fastify/cookie';
+import '@fastify/multipart';
+import { type ApiResponse } from '@tmlmobilidade/go-types-shared';
+import { HttpResponse } from '@tmlmobilidade/utils';
+import { type FastifyInstance as FastifyInstanceType, type FastifyReply as FastifyReplyType } from 'fastify';
+import { type ContextConfigDefault, type FastifyBaseLogger, type FastifySchema, type FastifyServerOptions, type FastifyTypeProviderDefault, type RawReplyDefaultExpression, type RawRequestDefaultExpression, type RawServerBase, type RawServerDefault, type RouteGenericInterface } from 'fastify';
+export { type FastifyRequest } from 'fastify';
+export type FastifyReply<T> = FastifyReplyType<RouteGenericInterface, RawServerBase, RawRequestDefaultExpression<RawServerBase>, RawReplyDefaultExpression<RawServerBase>, ContextConfigDefault, FastifySchema, FastifyTypeProviderDefault, ApiResponse<T> | HttpResponse<T> | ReadableStream>;
+export type FastifyResponse<T> = FastifyReplyType<RouteGenericInterface & {
+    Reply: ApiResponse<T> | HttpResponse<T>;
+}, RawServerBase, RawRequestDefaultExpression<RawServerBase>, RawReplyDefaultExpression<RawServerBase>, ContextConfigDefault, FastifySchema, FastifyTypeProviderDefault, ApiResponse<T> | HttpResponse<T>>;
+export type FastifyInstance = FastifyInstanceType<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, FastifyBaseLogger, FastifyTypeProviderDefault>;
+/**
+ * FastifyServiceOptions interface defines the options for the Fastify server.
+ * It extends FastifyServerOptions and adds optional properties for origin and port.
+ */
+export interface FastifyServiceOptions extends FastifyServerOptions {
+    /**
+     * The host on which the Fastify server will listen.
+     * If not provided, it defaults to '0.0.0.0'.
+     * @default '0.0.0.0'
+     */
+    host?: string;
+    /**
+     * The module name for the Fastify server.
+     * @default 'fastify'
+     */
+    module?: string;
+    /**
+     * The origin for CORS requests.
+     * Defaults to `true` if not provided.
+     * @default true
+     * @example 'https://example.com'
+     */
+    origin?: RegExp | string | true;
+    /**
+     * The port on which the Fastify server will listen.
+     * If not provided, it defaults to 5050.
+     * @default 5050
+     */
+    port?: number;
+}
+/**
+ * FastifyService is a singleton class that provides a Fastify server instance.
+ * It allows for setting up routes, plugins, and starting/stopping the server.
+ * This class is designed to be used as a service in a Node.js application.
+ * It uses the Fastify framework for building web applications and APIs.
+ */
+export declare class FastifyService {
+    private static _instance;
+    readonly server: FastifyInstance;
+    private readonly options;
+    /**
+     * Creates an instance of FastifyService.
+     * @param options The options for the Fastify server.
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of FastifyService.
+     * @param options The options for the Fastify server.
+     * @return The singleton instance of FastifyService.
+     */
+    static getInstance(options?: FastifyServiceOptions): FastifyService;
+    /**
+     * Starts the Fastify server.
+     * @return A promise that resolves to the URL of the Fastify server.
+     * @throws Will throw an error if the server fails to start.
+     */
+    start(moduleName?: string): Promise<string>;
+    /**
+     * Stops the Fastify server.
+     * @return A promise that resolves when the server is stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Sets the URL of the Fastify server.
+     * @return The URL of the Fastify server.
+     */
+    private _setupDefaultRoutes;
+    /**
+     * Sets up hooks for the Fastify server including error handling and response processing.
+     */
+    private _setupHooks;
+    /**
+     * Sets up the plugins for the Fastify server.
+     * @return A promise that resolves when the plugins are set up.
+     */
+    private _setupPlugins;
+}

package/dist/fastify-service.js

@@ -0,0 +1,303 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+/* * */
+import '@fastify/cors';
+import '@fastify/cookie';
+import '@fastify/multipart';
+/* * */
+import fastifyCookie from '@fastify/cookie';
+import fastifyCors from '@fastify/cors';
+import oneLineLogger from '@fastify/one-line-logger';
+import { HTTP_STATUS, HttpException } from '@tmlmobilidade/consts';
+import { initSentryNode, Logger } from '@tmlmobilidade/logger';
+import fastify from 'fastify';
+import { sendErrorApiResponse } from './response/error-response.js';
+const defaultFastifyServiceOptions = {
+    bodyLimit: 1024 * 1024 * 10, // 10MB
+    host: '0.0.0.0',
+    logger: true,
+    module: 'fastify',
+    origin: true,
+    port: 5050,
+    routerOptions: {
+        ignoreTrailingSlash: true,
+    },
+};
+const createLoggerOptions = (getModuleName) => ({
+    level: 'debug',
+    module: getModuleName(),
+    stream: oneLineLogger({
+        colorize: true, // nice colors,
+        colorizeObjects: true,
+        messageFormat(log, messageKey, _, extras) {
+            const c = extras.colors;
+            const moduleName = getModuleName();
+            const palette = {
+                error: c.redBright,
+                highlight: c.yellowBright, // URLs / routes
+                message: c.whiteBright,
+                method: c.greenBright,
+                methodLabel: c.gray,
+                path: c.blueBright,
+                pathLabel: c.gray,
+                pipe: c.cyanBright,
+                reqId: c.cyanBright,
+                reqIdLabel: c.gray,
+                stack: c.red,
+                status: c.yellowBright,
+                statusLabel: c.gray,
+                timestamp: c.cyanBright,
+            };
+            const colorize = (text) => {
+                const urlPattern = /(https?:\/\/[^\s]+)/g;
+                const routePattern = /Route "(.+?)"/g;
+                const pathPattern = /([A-Z]+):\/[^\s]+/g;
+                return text
+                    .replace(urlPattern, palette.highlight('$&'))
+                    .replace(routePattern, (_, r) => palette.highlight(`Route "${r}"`))
+                    .replace(pathPattern, palette.highlight('$&'));
+            };
+            const safe = (val, fallback = '') => typeof val === 'string' || typeof val === 'number' ? String(val) : fallback;
+            const formatMethod = (method) => {
+                if (!method)
+                    return '-----';
+                if (method === 'GET' || method === 'PUT')
+                    return `${method}  `;
+                return method.padEnd(5, '-');
+            };
+            const timestamp = new Date(log.time).toLocaleString('pt-PT', {
+                day: '2-digit',
+                hour: '2-digit',
+                minute: '2-digit',
+                month: '2-digit',
+                second: '2-digit',
+                year: 'numeric',
+            });
+            const reqId = log.reqId ? safe(log.reqId).padEnd(10, ' ') : Array(10).fill('-').join('');
+            const statusCode = typeof log.res === 'object' && log.res && 'statusCode' in log.res ? safe(log.res.statusCode).padEnd(3, '-') : '---';
+            const method = typeof log.req === 'object' && log.req && 'method' in log.req ? formatMethod(log.req.method ?? '') : '-----';
+            const path = typeof log.req === 'object' && log.req && 'url' in log.req ? safe(log.req.url).padEnd(10, ' ') : '-----';
+            // Extract error information
+            // Pino serializes errors, so log.err is an object with type, message, stack, etc.
+            const errorObj = log.err || log.error;
+            let errorMessage = safe(log[messageKey]);
+            let errorStack;
+            if (errorObj) {
+                // Pino serialized error object
+                errorMessage = errorObj.message || errorMessage;
+                errorStack = errorObj.stack;
+            }
+            else if (log[messageKey] instanceof Error) {
+                // Direct Error instance (shouldn't happen with Pino, but just in case)
+                errorMessage = log[messageKey].message || errorMessage;
+                errorStack = log[messageKey].stack;
+            }
+            const message = palette.message(colorize(errorMessage));
+            // Add stack trace on new lines, indented for readability
+            const stackTrace = errorStack ? `\n${palette.stack(errorStack.split('\n').map(line => `  ${line}`).join('\n'))}` : '';
+            const parts = [
+                palette.timestamp(timestamp),
+                palette.reqIdLabel(`reqId: ${palette.reqId(reqId)}`),
+                palette.statusLabel(`statusCode: ${palette.status(statusCode)}`),
+                palette.methodLabel(`Method: ${palette.method(method)}`),
+                palette.pathLabel(`Path: ${palette.path(path)}`),
+                message,
+            ];
+            const logMessage = palette.pipe(parts.join(' | ')) + stackTrace;
+            const shouldSendToSentry = message !== 'incoming request' && message !== 'request completed';
+            if (shouldSendToSentry) {
+                Logger.startNodeLogs({
+                    app: 'api',
+                    message: message,
+                    method: method,
+                    module: moduleName,
+                    path: path,
+                    reqId: reqId,
+                    severity: 'info',
+                    status: statusCode,
+                });
+            }
+            return logMessage;
+        },
+    }),
+});
+/**
+ * FastifyService is a singleton class that provides a Fastify server instance.
+ * It allows for setting up routes, plugins, and starting/stopping the server.
+ * This class is designed to be used as a service in a Node.js application.
+ * It uses the Fastify framework for building web applications and APIs.
+ */
+export class FastifyService {
+    //
+    static _instance;
+    server;
+    options;
+    /**
+     * Creates an instance of FastifyService.
+     * @param options The options for the Fastify server.
+     */
+    constructor(options) {
+        const mergedOptions = { ...defaultFastifyServiceOptions, ...options };
+        this.options = mergedOptions;
+        this.server = fastify({ ...mergedOptions, logger: createLoggerOptions(() => this.options.module ?? 'fastify') });
+        this._setupDefaultRoutes();
+        this._setupPlugins();
+    }
+    /**
+     * Gets the singleton instance of FastifyService.
+     * @param options The options for the Fastify server.
+     * @return The singleton instance of FastifyService.
+     */
+    static getInstance(options) {
+        if (!FastifyService._instance) {
+            // Create a new instance if it doesn't exist yet
+            FastifyService._instance = new FastifyService(options || {});
+            FastifyService._instance._setupHooks();
+        }
+        // Return the existing instance
+        return FastifyService._instance;
+    }
+    /**
+     * Starts the Fastify server.
+     * @return A promise that resolves to the URL of the Fastify server.
+     * @throws Will throw an error if the server fails to start.
+     */
+    async start(moduleName) {
+        if (moduleName)
+            this.options.module = moduleName;
+        try {
+            await initSentryNode();
+        }
+        catch (error) {
+            this.server.log.error({ err: error }, 'Error sending startup log to Sentry.');
+        }
+        try {
+            const serverUrl = await this.server.listen({
+                host: this.options.host,
+                port: this.options.port,
+            });
+            this.server.log.info(`Server is running at ${serverUrl}`);
+            return serverUrl;
+        }
+        catch (error) {
+            this.server.log.error({ err: error }, 'Error starting server.');
+            process.exit(1);
+        }
+    }
+    /**
+     * Stops the Fastify server.
+     * @return A promise that resolves when the server is stopped.
+     */
+    async stop() {
+        try {
+            await this.server.close();
+            console.log('Fastify server stopped.');
+        }
+        catch (error) {
+            this.server.log.error({ err: error }, error instanceof Error ? error.message : 'Error stopping server');
+            process.exit(1);
+        }
+    }
+    /**
+     * Sets the URL of the Fastify server.
+     * @return The URL of the Fastify server.
+     */
+    _setupDefaultRoutes() {
+        this.server.get('/', (req, res) => {
+            res.send('Jusi was here!');
+        });
+        this.server.get('/health', (_, res) => {
+            res.status(HTTP_STATUS.OK).send({ status: 'ok' });
+        });
+    }
+    /**
+     * Sets up hooks for the Fastify server including error handling and response processing.
+     */
+    _setupHooks() {
+        /**
+         * Decodes URI-encoded `id` path params so encoded slashes (e.g. `%2F`) are
+         * available as literal characters in route handlers.
+         */
+        this.server.addHook('preHandler', (request, _, done) => {
+            const params = request.params;
+            if (params.id !== undefined) {
+                try {
+                    params.id = decodeURIComponent(params.id);
+                }
+                catch {
+                    // Malformed URI sequence — keep original value
+                }
+            }
+            done();
+        });
+        /**
+         * Sets a global error handler for the Fastify server instance.
+         * This handler checks if the error is an instance of HttpException.
+         * If so, it sends a response with the appropriate status code and error message.
+         * This ensures consistent error responses for HTTP exceptions throughout the application.
+         */
+        this.server.setErrorHandler((error, request, reply) => {
+            // Log the error with full stack trace
+            const errorMessage = error instanceof Error ? error.message : 'Unhandled error';
+            this.server.log.error({ err: error }, errorMessage);
+            // Handle HttpException errors
+            if (error instanceof HttpException) {
+                if (error.statusCode === HTTP_STATUS.INTERNAL_SERVER_ERROR) {
+                    Logger.issue({ context: { action: 'errorHandler', feature: this.options.module, request, value: request.body }, level: 'error', messageOrError: error });
+                }
+                reply
+                    .status(error.statusCode)
+                    .send({
+                    data: undefined,
+                    error: error.message,
+                    statusCode: error.statusCode,
+                });
+            }
+            else {
+                Logger.issue({ context: { action: 'errorHandler', feature: this.options.module, request, value: request.body }, level: 'error', messageOrError: 'Internal server error' });
+                return sendErrorApiResponse(reply, {
+                    error: 'Internal server error',
+                    status_code: '500',
+                });
+            }
+        });
+        /**
+         * Adds an 'onSend' hook to the Fastify server instance.
+         * This hook intercepts every outgoing response before it is sent.
+         * It parses the payload as a JSON object (assuming it matches the HttpResponse<T> structure),
+         * and sets the HTTP status code of the reply to the value of 'statusCode' in the payload,
+         * defaulting to HTTP_STATUS.OK if not present.
+         * This ensures that the HTTP status code in the response matches the statusCode property
+         * in the application's response payload, providing consistent status handling.
+         */
+        this.server.addHook('onSend', (_, reply, payload, done) => {
+            try {
+                const payloadJson = JSON.parse(payload);
+                reply.code(payloadJson.statusCode ?? HTTP_STATUS.OK);
+            }
+            catch {
+                // Do nothing
+            }
+            finally {
+                done();
+            }
+        });
+    }
+    /**
+     * Sets up the plugins for the Fastify server.
+     * @return A promise that resolves when the plugins are set up.
+     */
+    async _setupPlugins() {
+        // CORS plugin
+        await this.server.register(fastifyCors, {
+            credentials: true,
+            methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'OPTIONS', 'DELETE'],
+            origin: this.options.origin,
+        });
+        // Cookie plugin
+        await this.server.register(fastifyCookie);
+        // Multipart plugin
+        // await this.server.register(fastifyMultipart, {
+        // 	limits: { fileSize: this.options.bodyLimit },
+        // });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './authorization-middleware.js';
+export * from './fastify-service.js';
+export * from './response/index.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './authorization-middleware.js';
+export * from './fastify-service.js';
+export * from './response/index.js';

package/dist/response/error-response.d.ts

@@ -0,0 +1,21 @@
+import { type FastifyReply } from '../fastify-service.js';
+import { type ApiResponseError } from '@tmlmobilidade/go-types-shared';
+import { type ApiResponseOptions } from './response-options.js';
+/**
+ * Options for sending an error API response.
+ */
+interface SendErrorResponseOptions extends ApiResponseOptions {
+    /**
+     * The error message to send in the error response.
+     */
+    error: ApiResponseError['error'];
+    /**
+     * The status code to send in the error response.
+     */
+    status_code: ApiResponseError['status_code'];
+}
+/**
+ * A function that sends an error HTTP response.
+ */
+export declare function sendErrorApiResponse<T>(reply: FastifyReply<T>, options: SendErrorResponseOptions): import("fastify").FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerBase, import("fastify").RawRequestDefaultExpression<import("fastify").RawServerBase>, import("fastify").RawReplyDefaultExpression<import("fastify").RawServerBase>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;
+export {};

package/dist/response/error-response.js

@@ -0,0 +1,30 @@
+/* * */
+import { Dates } from '@tmlmobilidade/go-utils-dates';
+import { getCacheControlHeader } from './response-options.js';
+/**
+ * A function that sends an error HTTP response.
+ */
+export function sendErrorApiResponse(reply, options) {
+    //
+    //
+    // Set the status code
+    if (!options.status_code)
+        throw new Error('Status code is required in sendErrorApiResponse()');
+    if (!options.error)
+        throw new Error('Error message is required in sendErrorApiResponse()');
+    reply.status(Number(options.status_code));
+    //
+    // Set the Cache-Control header
+    const cacheControlHeader = getCacheControlHeader(options?.max_age);
+    if (cacheControlHeader)
+        reply.header('Cache-Control', cacheControlHeader);
+    //
+    // Return with the prepared response
+    const response = {
+        data: null,
+        error: options.error,
+        status_code: options.status_code,
+        timestamp: Dates.now('local').unix_timestamp,
+    };
+    return reply.send(response);
+}

package/dist/response/index.d.ts

@@ -0,0 +1,3 @@
+export * from './error-response.js';
+export * from './response-options.js';
+export * from './success-response.js';

package/dist/response/index.js

@@ -0,0 +1,3 @@
+export * from './error-response.js';
+export * from './response-options.js';
+export * from './success-response.js';

package/dist/response/response-options.d.ts

@@ -0,0 +1,11 @@
+export interface ApiResponseOptions {
+    /**
+     * The maximum age of the response in seconds.
+     * @default undefined
+     */
+    max_age?: '1d' | '1h' | '1m' | '3s' | '5m' | '30m' | '30s' | null;
+}
+/**
+ * Receives a max_age value and returns the Cache-Control header.
+ */
+export declare function getCacheControlHeader(maxAge: ApiResponseOptions['max_age']): string;

package/dist/response/response-options.js

@@ -0,0 +1,30 @@
+/* * */
+/**
+ * Receives a max_age value and returns the Cache-Control header.
+ */
+export function getCacheControlHeader(maxAge) {
+    // Return empty if no max_age is provided
+    if (!maxAge)
+        return '';
+    // Return the Cache-Control header
+    let maxAgeSeconds;
+    if (typeof maxAge === 'number')
+        maxAgeSeconds = maxAge;
+    else if (maxAge === '3s')
+        maxAgeSeconds = 3;
+    else if (maxAge === '30s')
+        maxAgeSeconds = 30;
+    else if (maxAge === '1m')
+        maxAgeSeconds = 60;
+    else if (maxAge === '5m')
+        maxAgeSeconds = 300;
+    else if (maxAge === '30m')
+        maxAgeSeconds = 1800;
+    else if (maxAge === '1h')
+        maxAgeSeconds = 3600;
+    else if (maxAge === '1d')
+        maxAgeSeconds = 86400;
+    else
+        throw new Error(`Invalid max_age: ${maxAge}`);
+    return `public, max-age=${maxAgeSeconds}`;
+}

package/dist/response/success-response.d.ts

@@ -0,0 +1,32 @@
+import { type FastifyReply } from '../fastify-service.js';
+import { type ApiResponseSuccess } from '@tmlmobilidade/go-types-shared';
+import { type ApiResponseOptions } from './response-options.js';
+/**
+ * Options for sending a successful API response.
+ */
+interface SendSuccessApiResponseOptions<T> extends ApiResponseOptions {
+    /**
+     * The status code to send in the successful response.
+     * Defaults to `200`.
+     */
+    status_code?: ApiResponseSuccess<T>['status_code'];
+}
+/**
+ * A function that sends a successful HTTP response.
+ * @example
+ * ```ts
+ * sendSuccessApiResponse(reply, { message: 'Hello, world!' });
+ * ```
+ * @example
+ * ```ts
+ * // With a different status code (e.g. 201 Created)
+ * sendSuccessApiResponse<Item[]>(reply, queryResult, { status_code: '201' });
+ * ```
+ * @example
+ * ```ts
+ * // With a cache control header (e.g. 1 minute)
+ * sendSuccessApiResponse<PublicResource>(reply, queryResult, { max_age: 60 });
+ * ```
+ */
+export declare function sendSuccessApiResponse<T>(reply: FastifyReply<T>, data: T, options?: SendSuccessApiResponseOptions<T>): import("fastify").FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerBase, import("fastify").RawRequestDefaultExpression<import("fastify").RawServerBase>, import("fastify").RawReplyDefaultExpression<import("fastify").RawServerBase>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;
+export {};

package/dist/response/success-response.js

@@ -0,0 +1,41 @@
+/* * */
+import { Dates } from '@tmlmobilidade/go-utils-dates';
+import { getCacheControlHeader } from './response-options.js';
+/**
+ * A function that sends a successful HTTP response.
+ * @example
+ * ```ts
+ * sendSuccessApiResponse(reply, { message: 'Hello, world!' });
+ * ```
+ * @example
+ * ```ts
+ * // With a different status code (e.g. 201 Created)
+ * sendSuccessApiResponse<Item[]>(reply, queryResult, { status_code: '201' });
+ * ```
+ * @example
+ * ```ts
+ * // With a cache control header (e.g. 1 minute)
+ * sendSuccessApiResponse<PublicResource>(reply, queryResult, { max_age: 60 });
+ * ```
+ */
+export function sendSuccessApiResponse(reply, data, options) {
+    //
+    //
+    // Set the status code
+    const statusCodeValue = options?.status_code || '200';
+    reply.status(Number(statusCodeValue));
+    //
+    // Set the Cache-Control header
+    const cacheControlHeader = getCacheControlHeader(options?.max_age);
+    if (cacheControlHeader)
+        reply.header('Cache-Control', cacheControlHeader);
+    //
+    // Return with the prepared response
+    const response = {
+        data,
+        error: null,
+        status_code: statusCodeValue,
+        timestamp: Dates.now('local').unix_timestamp,
+    };
+    return reply.send(response);
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@tmlmobilidade/go-clients-fastify",
+	"version": "20260828.1636.54",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src && tsc --noEmit",
+		"lint:fix": "eslint ./src --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@fastify/cookie": "11.1.2",
+		"@fastify/cors": "11.3.0",
+		"@fastify/multipart": "10.1.0",
+		"@fastify/one-line-logger": "2.1.0",
+		"@tmlmobilidade/consts": "*",
+		"@tmlmobilidade/go-providers-auth": "*",
+		"@tmlmobilidade/go-types-core": "*",
+		"@tmlmobilidade/go-types-permissions": "*",
+		"@tmlmobilidade/go-types-shared": "*",
+		"@tmlmobilidade/go-utils-dates": "*",
+		"@tmlmobilidade/logger": "*",
+		"@tmlmobilidade/utils": "*",
+		"fastify": "5.11.2"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/node": "26.1.2",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}