@zauru-sdk/utils 6.14.0 → 6.16.0

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 export * from "./zauru/api.loaders.js";
+export * from "./zauru/auth.loaders.js";
 export * from "./zauru/automatic-number.utils.js";
 export * from "./zauru/bitacora-edicion-masiva.utils.js";
 export * from "./zauru/bundles.utils.js";

package/dist/esm/zauru/auth.loaders.js

@@ -0,0 +1,141 @@
+import { redirect } from "@remix-run/node";
+import { config } from "@zauru-sdk/config";
+import { commitSession, destroySession, getRefreshSession, getSession, loginWebApp, } from "@zauru-sdk/services";
+const loginErrorPayload = (description, title) => ({
+    error: true,
+    type: "error",
+    title: title ??
+        "Ocurrió un error al cargar la información de inicio de sesión (Carga de webapp)",
+    description,
+});
+const isDenied = (result) => result === false;
+const authorizeUrl = (request) => {
+    const url = new URL(request.url);
+    const hostname = `${url.port ? "http://" : "https://"}${url.hostname}${url.port ? `:${url.port}` : ""}`;
+    return `${config.oauthBaseURL}/dialog/authorize?client_id=${config.oauthClientID}&response_type=code&redirect_uri=${hostname}/login`;
+};
+export function createLoginLoader() {
+    return async () => Response.json({});
+}
+/**
+ * Remix action for `/login`: OAuth authorize, `loginWebApp`, cookie commit.
+ * `afterLogin` runs before `commitSession`. `requireAccess` can deny after
+ * a successful OAuth exchange or when a session already has `code`.
+ */
+export function createLoginAction(extras) {
+    return async ({ request }) => {
+        const formData = await request.formData();
+        const { action, ...values } = Object.fromEntries(formData);
+        if (action === "redirect") {
+            const cookie = values?.cookie?.toString() ?? "";
+            return redirect("/home", {
+                headers: {
+                    "Set-Cookie": cookie,
+                },
+            });
+        }
+        const codeValue = new URL(request.url).searchParams.get("code") ?? "";
+        const cookie = request.headers.get("Cookie") ?? "";
+        const session = await getSession(cookie);
+        if (!session.has("code") && !codeValue) {
+            return redirect(authorizeUrl(request));
+        }
+        if (session.has("code")) {
+            if (isDenied(extras?.requireAccess?.(session))) {
+                return redirect("/");
+            }
+            return redirect("/home");
+        }
+        const loginResponse = await loginWebApp(session, codeValue, cookie);
+        if (loginResponse.error || !loginResponse.data) {
+            return Response.json(loginErrorPayload(loginResponse.userMsg?.toString() ?? ""));
+        }
+        if (isDenied(extras?.requireAccess?.(session))) {
+            return Response.json(loginErrorPayload("No tienes permiso para acceder a esta aplicación. Si crees que esto es un error, contacta al administrador.", "Acceso denegado"));
+        }
+        if (extras?.afterLogin) {
+            await extras.afterLogin({
+                request,
+                session,
+                headers: loginResponse.data.headers,
+                loginData: loginResponse.data,
+            });
+        }
+        const expires = new Date();
+        expires.setSeconds(expires.getSeconds() + Number(config.expirationDurationInSeconds));
+        return Response.json({
+            ...loginResponse.data,
+            cookie: await commitSession(session, { expires }),
+        });
+    };
+}
+/**
+ * Guard for `/home` and `/reload-catalogs`: no `username` → `/`.
+ */
+export function createSessionGuardLoader(extras) {
+    return async ({ request }) => {
+        const session = await getSession(request.headers.get("Cookie"));
+        if (!session.has("username")) {
+            return redirect("/");
+        }
+        if (isDenied(extras?.requireAccess?.(session))) {
+            return redirect("/");
+        }
+        return Response.json({});
+    };
+}
+export function createLogoutLoader(extras) {
+    return createSessionGuardLoader(extras);
+}
+export function createLogoutAction() {
+    return async ({ request }) => {
+        const session = await getSession(request.headers.get("Cookie"));
+        return redirect(`${config.oauthBaseURL}/logout`, {
+            headers: {
+                "Set-Cookie": await destroySession(session),
+            },
+        });
+    };
+}
+/**
+ * `/` welcome: existing session (and optional access) → `/home`.
+ */
+export function createIndexLoader(extras) {
+    return async ({ request }) => {
+        const session = await getSession(request.headers.get("Cookie"));
+        if (session.has("username")) {
+            if (isDenied(extras?.requireAccess?.(session))) {
+                return Response.json({});
+            }
+            return redirect("/home");
+        }
+        return Response.json({});
+    };
+}
+/**
+ * `/reload-catalogs`: session guard plus optional cookie refresh.
+ */
+export function createReloadCatalogsLoader(extras) {
+    return async ({ request }) => {
+        const session = await getSession(request.headers.get("Cookie"));
+        if (!session.has("username")) {
+            return redirect("/");
+        }
+        if (isDenied(extras?.requireAccess?.(session))) {
+            return redirect("/");
+        }
+        try {
+            const refreshSession = await getRefreshSession(request);
+            return Response.json({}, refreshSession
+                ? {
+                    headers: {
+                        "Set-Cookie": refreshSession,
+                    },
+                }
+                : {});
+        }
+        catch {
+            return Response.json({});
+        }
+    };
+}

package/dist/esm/zauru/cloudwatch-logger.server.js

@@ -0,0 +1,426 @@
+import { CloudWatchLogsClient, CreateLogGroupCommand, CreateLogStreamCommand, DescribeLogStreamsCommand, PutLogEventsCommand, ResourceAlreadyExistsException, InvalidSequenceTokenException, DataAlreadyAcceptedException, } from "@aws-sdk/client-cloudwatch-logs";
+/**
+ * Server logger for AWS CloudWatch Logs, with `console.*` as a fallback so
+ * events still appear in the host (Netlify) logs.
+ *
+ * Enable by setting `CLOUDWATCH_LOG_GROUP` plus any complete AWS credential
+ * prefix (first match wins):
+ * - `CLOUDWATCH_AWS_REGION` / `CLOUDWATCH_AWS_ACCESS_KEY_ID` / `CLOUDWATCH_AWS_SECRET_ACCESS_KEY`
+ * - `APPOCUS_AWS_*`
+ * - `C4PINOS_AWS_*`
+ * - `AWS_*`
+ *
+ * Missing env → no-op for CloudWatch (still logs to console). Never throws.
+ *
+ * Naming:
+ * - Log group = `CLOUDWATCH_LOG_GROUP`
+ * - Group tags: `Project=<logGroup>`, `Env=<APP_ENV>`
+ * - Streams: `<APP_ENV>/client`, `<APP_ENV>/server`, `<APP_ENV>/background-functions`
+ */
+const MAX_EVENT_CHARS = 240_000;
+const MAX_BATCH_EVENTS = 50;
+const AWS_CANDIDATES = [
+    {
+        region: "CLOUDWATCH_AWS_REGION",
+        key: "CLOUDWATCH_AWS_ACCESS_KEY_ID",
+        secret: "CLOUDWATCH_AWS_SECRET_ACCESS_KEY",
+        label: "CLOUDWATCH_AWS_*",
+    },
+    {
+        region: "APPOCUS_AWS_REGION",
+        key: "APPOCUS_AWS_ACCESS_KEY_ID",
+        secret: "APPOCUS_AWS_SECRET_ACCESS_KEY",
+        label: "APPOCUS_AWS_*",
+    },
+    {
+        region: "C4PINOS_AWS_REGION",
+        key: "C4PINOS_AWS_ACCESS_KEY_ID",
+        secret: "C4PINOS_AWS_SECRET_ACCESS_KEY",
+        label: "C4PINOS_AWS_*",
+    },
+    {
+        region: "AWS_REGION",
+        key: "AWS_ACCESS_KEY_ID",
+        secret: "AWS_SECRET_ACCESS_KEY",
+        label: "AWS_*",
+    },
+];
+let client = null;
+let clientKey = null;
+/** Sequence token per stream. Survives while the lambda instance is warm. */
+const sequenceTokens = {};
+/** Serializes PutLogEvents so sequence tokens are not overwritten. */
+let putChain = Promise.resolve();
+function envTrim(name) {
+    const v = process.env[name];
+    if (!v || v.trim() === "")
+        return undefined;
+    return v.trim();
+}
+function resolveAwsCreds() {
+    for (const c of AWS_CANDIDATES) {
+        const region = envTrim(c.region);
+        const accessKeyId = envTrim(c.key);
+        const secretAccessKey = envTrim(c.secret);
+        if (region && accessKeyId && secretAccessKey) {
+            return { region, accessKeyId, secretAccessKey, prefixLabel: c.label };
+        }
+    }
+    return null;
+}
+function getLogGroup() {
+    return envTrim("CLOUDWATCH_LOG_GROUP");
+}
+function getEnvName() {
+    return envTrim("APP_ENV") ?? "development";
+}
+function getDefaultAppVersion() {
+    return envTrim("APP_VERSION") ?? envTrim("npm_package_version") ?? "unknown";
+}
+/**
+ * Introspection for smoke tests / diagnostics. Never returns secrets.
+ */
+export function resolveCloudWatchConfig() {
+    const logGroup = getLogGroup();
+    const creds = resolveAwsCreds();
+    const appEnv = getEnvName();
+    const appVersion = getDefaultAppVersion();
+    if (!logGroup && !creds) {
+        return {
+            enabled: false,
+            appEnv,
+            appVersion,
+            skipReason: "faltan CLOUDWATCH_LOG_GROUP y credenciales AWS (CLOUDWATCH_AWS_*, APPOCUS_AWS_*, C4PINOS_AWS_* o AWS_*)",
+        };
+    }
+    if (!logGroup) {
+        return {
+            enabled: false,
+            region: creds?.region,
+            prefixLabel: creds?.prefixLabel,
+            appEnv,
+            appVersion,
+            skipReason: "falta CLOUDWATCH_LOG_GROUP",
+        };
+    }
+    if (!creds) {
+        return {
+            enabled: false,
+            logGroup,
+            appEnv,
+            appVersion,
+            skipReason: "faltan credenciales AWS (CLOUDWATCH_AWS_*, APPOCUS_AWS_*, C4PINOS_AWS_* o AWS_*)",
+        };
+    }
+    return {
+        enabled: true,
+        logGroup,
+        region: creds.region,
+        prefixLabel: creds.prefixLabel,
+        appEnv,
+        appVersion,
+    };
+}
+export function isCloudWatchEnabled() {
+    return resolveCloudWatchConfig().enabled;
+}
+function getClient() {
+    const creds = resolveAwsCreds();
+    if (!creds) {
+        throw new Error("CloudWatch deshabilitado: faltan credenciales AWS");
+    }
+    const key = `${creds.prefixLabel}:${creds.region}:${creds.accessKeyId}`;
+    if (!client || clientKey !== key) {
+        client = new CloudWatchLogsClient({
+            region: creds.region,
+            credentials: {
+                accessKeyId: creds.accessKeyId,
+                secretAccessKey: creds.secretAccessKey,
+            },
+        });
+        clientKey = key;
+    }
+    return client;
+}
+function streamName(origin) {
+    const env = getEnvName();
+    switch (origin) {
+        case "client":
+            return `${env}/client`;
+        case "server":
+            return `${env}/server`;
+        case "background":
+            return `${env}/background-functions`;
+        default: {
+            const _never = origin;
+            throw new Error(`Origen de log no soportado: ${String(_never)}`);
+        }
+    }
+}
+async function ensureStreamExists(cw, logGroup, stream) {
+    try {
+        await cw.send(new CreateLogGroupCommand({
+            logGroupName: logGroup,
+            tags: {
+                Project: logGroup,
+                Env: getEnvName(),
+            },
+        }));
+    }
+    catch (err) {
+        if (!(err instanceof ResourceAlreadyExistsException)) {
+            // IAM without logs:TagResource → CreateLogGroup with tags fails.
+            // Retry without tags (CreateLogGroup only).
+            try {
+                await cw.send(new CreateLogGroupCommand({
+                    logGroupName: logGroup,
+                }));
+            }
+            catch (retryErr) {
+                if (!(retryErr instanceof ResourceAlreadyExistsException)) {
+                    console.error("[observability] No se pudo crear el log group CloudWatch:", retryErr instanceof Error ? retryErr.message : retryErr);
+                }
+            }
+        }
+    }
+    try {
+        await cw.send(new CreateLogStreamCommand({
+            logGroupName: logGroup,
+            logStreamName: stream,
+        }));
+    }
+    catch (err) {
+        if (!(err instanceof ResourceAlreadyExistsException)) {
+            console.error("[observability] No se pudo crear el log stream CloudWatch:", err instanceof Error ? err.message : err);
+        }
+    }
+}
+/** Current sequence token of the stream (for cold starts). */
+async function fetchSequenceToken(cw, logGroup, stream) {
+    try {
+        const res = await cw.send(new DescribeLogStreamsCommand({
+            logGroupName: logGroup,
+            logStreamNamePrefix: stream,
+            limit: 1,
+        }));
+        return res.logStreams?.[0]?.uploadSequenceToken;
+    }
+    catch {
+        return undefined;
+    }
+}
+const RESERVED_KEYS = new Set([
+    "message",
+    "stack",
+    "url",
+    "method",
+    "userAgent",
+    "userId",
+    "appVersion",
+    "timestamp",
+    "source",
+    "level",
+]);
+function levelPrefix(origin, level) {
+    if (origin !== "background") {
+        return "[ERROR]";
+    }
+    switch (level) {
+        case "error":
+            return "[ERROR]";
+        case "warn":
+            return "[WARN]";
+        case "info":
+            return "[INFO]";
+        case undefined:
+            return "[INFO]";
+        default: {
+            const _never = level;
+            return String(_never);
+        }
+    }
+}
+function buildLogLine(origin, payload) {
+    const ts = new Date(payload.timestamp ?? Date.now()).toISOString();
+    const source = payload.source ?? "unknown";
+    const parts = [
+        levelPrefix(origin, payload.level),
+        `[${origin}]`,
+        `[${source}]`,
+        ts,
+        payload.message,
+    ];
+    if (payload.url)
+        parts.push(`url=${payload.url}`);
+    if (payload.method)
+        parts.push(`method=${payload.method}`);
+    if (payload.userId != null)
+        parts.push(`user=${payload.userId}`);
+    if (payload.appVersion)
+        parts.push(`v=${payload.appVersion}`);
+    for (const [k, v] of Object.entries(payload)) {
+        if (RESERVED_KEYS.has(k))
+            continue;
+        try {
+            parts.push(`${k}=${typeof v === "string" ? v : JSON.stringify(v)}`);
+        }
+        catch {
+            parts.push(`${k}=[unserializable]`);
+        }
+    }
+    if (payload.stack)
+        parts.push(`\n${payload.stack}`);
+    return parts.join(" ");
+}
+function truncateEvent(message) {
+    if (message.length <= MAX_EVENT_CHARS)
+        return message;
+    return `${message.slice(0, MAX_EVENT_CHARS)}…[truncated]`;
+}
+async function putEvents(cw, logGroup, stream, messages) {
+    let sequenceToken = sequenceTokens[stream];
+    if (!sequenceToken) {
+        sequenceToken = await fetchSequenceToken(cw, logGroup, stream);
+    }
+    const startedAt = Date.now();
+    const input = {
+        logGroupName: logGroup,
+        logStreamName: stream,
+        logEvents: messages.map((m, index) => ({
+            message: truncateEvent(m),
+            timestamp: startedAt + index,
+        })),
+        sequenceToken,
+    };
+    try {
+        const res = await cw.send(new PutLogEventsCommand(input));
+        sequenceTokens[stream] = res.nextSequenceToken;
+    }
+    catch (err) {
+        if (err instanceof InvalidSequenceTokenException) {
+            const expected = err.expectedSequenceToken;
+            if (!expected)
+                throw err;
+            const res = await cw.send(new PutLogEventsCommand({ ...input, sequenceToken: expected }));
+            sequenceTokens[stream] = res.nextSequenceToken;
+        }
+        else if (err instanceof DataAlreadyAcceptedException) {
+            sequenceTokens[stream] = err.expectedSequenceToken;
+        }
+        else {
+            throw err;
+        }
+    }
+}
+function serializePut(fn) {
+    const next = putChain.then(fn, fn);
+    putChain = next.then(() => undefined, () => undefined);
+    return next;
+}
+async function emitToCloudWatch(origin, lines) {
+    if (lines.length === 0) {
+        return { status: "skipped", reason: "sin eventos" };
+    }
+    const cfg = resolveCloudWatchConfig();
+    if (!cfg.enabled || !cfg.logGroup) {
+        return {
+            status: "skipped",
+            reason: cfg.skipReason ?? "CloudWatch deshabilitado",
+        };
+    }
+    try {
+        const cw = getClient();
+        const logGroup = cfg.logGroup;
+        const stream = streamName(origin);
+        await ensureStreamExists(cw, logGroup, stream);
+        for (let i = 0; i < lines.length; i += MAX_BATCH_EVENTS) {
+            const chunk = lines.slice(i, i + MAX_BATCH_EVENTS);
+            await serializePut(() => putEvents(cw, logGroup, stream, chunk));
+        }
+        return { status: "sent", logGroup, stream };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        console.error("[observability] Falló envío a CloudWatch:", err);
+        return { status: "failed", error };
+    }
+}
+/**
+ * Sends an event to CloudWatch. Never throws.
+ * For client/server also prints with `console.error` (Netlify fallback).
+ */
+export async function logEvent(origin, payload) {
+    const line = buildLogLine(origin, {
+        ...payload,
+        appVersion: payload.appVersion ?? getDefaultAppVersion(),
+    });
+    if (origin !== "background") {
+        console.error(`[observability] ${line}`);
+    }
+    else {
+        console.log(`[observability] ${line}`);
+    }
+    return emitToCloudWatch(origin, [line]);
+}
+/**
+ * Sends an error event to CloudWatch (and console.error as fallback).
+ * Never throws: if CloudWatch fails, the error still lands in host logs.
+ */
+export async function logError(origin, payload) {
+    return logEvent(origin, { ...payload, level: "error" });
+}
+function formatConsoleArgs(args) {
+    return args
+        .map((arg) => {
+        if (typeof arg === "string")
+            return arg;
+        if (arg instanceof Error)
+            return arg.stack ?? arg.message;
+        try {
+            return JSON.stringify(arg);
+        }
+        catch {
+            return String(arg);
+        }
+    })
+        .join(" ");
+}
+/**
+ * Wraps a Netlify background handler: intercepts console.log/error/warn
+ * during the invocation, prefixes `[functionName]:`, and flushes to the
+ * `<APP_ENV>/background-functions` stream before returning (so logs are not
+ * lost when Netlify freezes the isolate).
+ */
+export function withBackgroundLogs(functionName, handler) {
+    return async (event, context) => {
+        const prefix = `[${functionName}]:`;
+        const origLog = console.log;
+        const origError = console.error;
+        const origWarn = console.warn;
+        const buffer = [];
+        const enqueue = (args) => {
+            buffer.push(`${prefix} ${formatConsoleArgs(args)}`);
+        };
+        console.log = (...args) => {
+            origLog(prefix, ...args);
+            enqueue(args);
+        };
+        console.error = (...args) => {
+            origError(prefix, ...args);
+            enqueue(args);
+        };
+        console.warn = (...args) => {
+            origWarn(prefix, ...args);
+            enqueue(args);
+        };
+        try {
+            return await handler(event, context);
+        }
+        finally {
+            console.log = origLog;
+            console.error = origError;
+            console.warn = origWarn;
+            await emitToCloudWatch("background", buffer);
+        }
+    };
+}

package/dist/esm/zauru/cloudwatch-remix.server.js

@@ -0,0 +1,96 @@
+import { getSession } from "@zauru-sdk/services";
+import { logError } from "./cloudwatch-logger.server.js";
+const MAX_MESSAGE_LENGTH = 8000;
+const MAX_STACK_LENGTH = 16000;
+function truncate(value, max) {
+    if (!value)
+        return undefined;
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max)}…[truncated]`;
+}
+function isRouteErrorResponse(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "status" in error &&
+        "statusText" in error &&
+        typeof error.status === "number");
+}
+/**
+ * Remix `handleError` for `entry.server.tsx`. Captures loader/action errors
+ * and sends them to CloudWatch (`<APP_ENV>/server`). Never throws.
+ */
+export async function handleError(error, { request }) {
+    if (request.signal.aborted)
+        return;
+    if (isRouteErrorResponse(error) && error.status < 500)
+        return;
+    const message = error instanceof Error
+        ? error.message
+        : isRouteErrorResponse(error)
+            ? `${error.status} ${error.statusText}`
+            : typeof error === "object" && error !== null && "message" in error
+                ? String(error.message)
+                : String(error);
+    await logError("server", {
+        message,
+        stack: error instanceof Error ? error.stack : undefined,
+        url: request.url,
+        method: request.method,
+        source: request.method.toUpperCase() === "GET" ? "loader" : "action",
+    });
+}
+/**
+ * Remix action for `POST /api/client-errors`.
+ *
+ * Best-effort: session is optional (errors can happen on /login), but if a
+ * cookie is present the username is attached. Never requires app access.
+ */
+export function createClientErrorsAction() {
+    return async ({ request }) => {
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ success: false, error: "Body inválido (se esperaba JSON)." }, { status: 400 });
+        }
+        if (!body || typeof body !== "object" || !body.message) {
+            return Response.json({ success: false, error: "Falta `message` en el payload." }, { status: 400 });
+        }
+        let userId;
+        try {
+            const cookie = request.headers.get("Cookie") ?? "";
+            const session = await getSession(cookie);
+            const username = session.get("username");
+            if (typeof username === "string" && username.length > 0) {
+                userId = username;
+            }
+        }
+        catch {
+            // Ignore: error reporting must not depend on the session.
+        }
+        const source = typeof body.source === "string" && body.source.length <= 200
+            ? body.source
+            : "unknown";
+        await logError("client", {
+            message: truncate(String(body.message), MAX_MESSAGE_LENGTH) ?? "Sin mensaje",
+            stack: truncate(typeof body.stack === "string" ? body.stack : undefined, MAX_STACK_LENGTH),
+            url: typeof body.url === "string" && body.url.length <= 2000
+                ? body.url
+                : undefined,
+            userAgent: typeof body.userAgent === "string" && body.userAgent.length <= 1000
+                ? body.userAgent
+                : undefined,
+            appVersion: typeof body.appVersion === "string" && body.appVersion.length <= 100
+                ? body.appVersion
+                : undefined,
+            timestamp: typeof body.timestamp === "number" && Number.isFinite(body.timestamp)
+                ? body.timestamp
+                : Date.now(),
+            userId,
+            source,
+        });
+        return new Response(null, { status: 204 });
+    };
+}

package/dist/esm/zauru/cloudwatch.server.js

@@ -0,0 +1,8 @@
+/**
+ * Server-only CloudWatch observability for Remix webapps.
+ *
+ * Import from `@zauru-sdk/utils/cloudwatch.server` (not the main barrel) so
+ * the AWS SDK stays out of the client bundle.
+ */
+export { isCloudWatchEnabled, logError, logEvent, resolveCloudWatchConfig, withBackgroundLogs, } from "./cloudwatch-logger.server.js";
+export { createClientErrorsAction, handleError, } from "./cloudwatch-remix.server.js";

package/dist/esm/zauru/remix-entry.server.js

@@ -0,0 +1,8 @@
+/**
+ * Remix 2 SSR entry + CloudWatch `handleError`.
+ *
+ * ```ts
+ * export { handleRequest as default, handleError } from "@zauru-sdk/utils/remix-entry.server";
+ * ```
+ */
+export { handleRequest, handleError } from "./remix-handle-request.server.js";

package/dist/esm/zauru/remix-handle-request.server.js

@@ -0,0 +1,93 @@
+import { createElement } from "react";
+import { PassThrough } from "node:stream";
+import { createReadableStreamFromReadable } from "@remix-run/node";
+import { RemixServer } from "@remix-run/react";
+import { renderToPipeableStream } from "react-dom/server";
+import { handleError } from "./cloudwatch-remix.server.js";
+const ABORT_DELAY = 5_000;
+function isBotRequest(userAgent) {
+    if (!userAgent)
+        return false;
+    return /bot|crawler|spider|crawling|facebookexternalhit|slurp|bingpreview/i.test(userAgent);
+}
+/**
+ * Remix 2 `handleRequest` (pipeable SSR). Use with `handleError` from
+ * `@zauru-sdk/utils/cloudwatch.server` in `app/entry.server.tsx`:
+ *
+ * ```ts
+ * export { handleRequest as default, handleError } from "@zauru-sdk/utils/remix-entry.server";
+ * ```
+ *
+ * Remix 1 apps keep their own `renderToString` entry; they have no `handleError`.
+ */
+export function handleRequest(request, responseStatusCode, responseHeaders, remixContext, _loadContext) {
+    const prohibitOutOfOrderStreaming = isBotRequest(request.headers.get("user-agent")) || remixContext.isSpaMode;
+    return prohibitOutOfOrderStreaming
+        ? handleBotRequest(request, responseStatusCode, responseHeaders, remixContext)
+        : handleBrowserRequest(request, responseStatusCode, responseHeaders, remixContext);
+}
+function handleBotRequest(request, responseStatusCode, responseHeaders, remixContext) {
+    return new Promise((resolve, reject) => {
+        let shellRendered = false;
+        const { pipe, abort } = renderToPipeableStream(createElement(RemixServer, {
+            context: remixContext,
+            url: request.url,
+            abortDelay: ABORT_DELAY,
+        }), {
+            onAllReady() {
+                shellRendered = true;
+                const body = new PassThrough();
+                const stream = createReadableStreamFromReadable(body);
+                responseHeaders.set("Content-Type", "text/html");
+                resolve(new Response(stream, {
+                    headers: responseHeaders,
+                    status: responseStatusCode,
+                }));
+                pipe(body);
+            },
+            onShellError(error) {
+                reject(error);
+            },
+            onError(error) {
+                responseStatusCode = 500;
+                if (shellRendered) {
+                    console.error(error);
+                }
+            },
+        });
+        setTimeout(abort, ABORT_DELAY);
+    });
+}
+function handleBrowserRequest(request, responseStatusCode, responseHeaders, remixContext) {
+    return new Promise((resolve, reject) => {
+        let shellRendered = false;
+        const { pipe, abort } = renderToPipeableStream(createElement(RemixServer, {
+            context: remixContext,
+            url: request.url,
+            abortDelay: ABORT_DELAY,
+        }), {
+            onShellReady() {
+                shellRendered = true;
+                const body = new PassThrough();
+                const stream = createReadableStreamFromReadable(body);
+                responseHeaders.set("Content-Type", "text/html");
+                resolve(new Response(stream, {
+                    headers: responseHeaders,
+                    status: responseStatusCode,
+                }));
+                pipe(body);
+            },
+            onShellError(error) {
+                reject(error);
+            },
+            onError(error) {
+                responseStatusCode = 500;
+                if (shellRendered) {
+                    console.error(error);
+                }
+            },
+        });
+        setTimeout(abort, ABORT_DELAY);
+    });
+}
+export { handleError };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./zauru/api.loaders.js";
+export * from "./zauru/auth.loaders.js";
 export * from "./zauru/automatic-number.utils.js";
 export * from "./zauru/bitacora-edicion-masiva.utils.js";
 export * from "./zauru/bundles.utils.js";

package/dist/zauru/auth.loaders.d.ts

@@ -0,0 +1,40 @@
+import type { ActionFunction, LoaderFunction } from "@remix-run/node";
+import { getSession, loginWebApp } from "@zauru-sdk/services";
+export type AuthSession = Awaited<ReturnType<typeof getSession>>;
+export type LoginWebAppData = NonNullable<Awaited<ReturnType<typeof loginWebApp>>["data"]>;
+export type AuthAccessExtras = {
+    /**
+     * Return `false` to deny. Throw `redirect(...)` to send the user elsewhere.
+     * Any other return (including `void`) allows access.
+     */
+    requireAccess?: (session: AuthSession) => boolean | void;
+};
+export type LoginActionExtras = AuthAccessExtras & {
+    afterLogin?: (ctx: {
+        request: Request;
+        session: AuthSession;
+        headers: LoginWebAppData["headers"];
+        loginData: LoginWebAppData;
+    }) => Promise<void>;
+};
+export declare function createLoginLoader(): LoaderFunction;
+/**
+ * Remix action for `/login`: OAuth authorize, `loginWebApp`, cookie commit.
+ * `afterLogin` runs before `commitSession`. `requireAccess` can deny after
+ * a successful OAuth exchange or when a session already has `code`.
+ */
+export declare function createLoginAction(extras?: LoginActionExtras): ActionFunction;
+/**
+ * Guard for `/home` and `/reload-catalogs`: no `username` → `/`.
+ */
+export declare function createSessionGuardLoader(extras?: AuthAccessExtras): LoaderFunction;
+export declare function createLogoutLoader(extras?: AuthAccessExtras): LoaderFunction;
+export declare function createLogoutAction(): ActionFunction;
+/**
+ * `/` welcome: existing session (and optional access) → `/home`.
+ */
+export declare function createIndexLoader(extras?: AuthAccessExtras): LoaderFunction;
+/**
+ * `/reload-catalogs`: session guard plus optional cookie refresh.
+ */
+export declare function createReloadCatalogsLoader(extras?: AuthAccessExtras): LoaderFunction;

package/dist/zauru/cloudwatch-logger.server.d.ts

@@ -0,0 +1,58 @@
+export type LogOrigin = "client" | "server" | "background";
+export type LogLevel = "error" | "info" | "warn";
+export type CloudWatchConfigInfo = {
+    enabled: boolean;
+    logGroup?: string;
+    region?: string;
+    prefixLabel?: string;
+    appEnv: string;
+    appVersion: string;
+    skipReason?: string;
+};
+/**
+ * Introspection for smoke tests / diagnostics. Never returns secrets.
+ */
+export declare function resolveCloudWatchConfig(): CloudWatchConfigInfo;
+export declare function isCloudWatchEnabled(): boolean;
+export interface LogPayload {
+    message: string;
+    stack?: string;
+    url?: string;
+    method?: string;
+    userAgent?: string;
+    userId?: string | number | null;
+    appVersion?: string;
+    timestamp?: number;
+    /** Sub-origin: errorBoundary, window.onerror, unhandledrejection, loader, action. */
+    source?: string;
+    level?: LogLevel;
+    [key: string]: unknown;
+}
+export type LogErrorResult = {
+    status: "sent";
+    logGroup: string;
+    stream: string;
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "failed";
+    error: string;
+};
+/**
+ * Sends an event to CloudWatch. Never throws.
+ * For client/server also prints with `console.error` (Netlify fallback).
+ */
+export declare function logEvent(origin: LogOrigin, payload: LogPayload): Promise<LogErrorResult>;
+/**
+ * Sends an error event to CloudWatch (and console.error as fallback).
+ * Never throws: if CloudWatch fails, the error still lands in host logs.
+ */
+export declare function logError(origin: "client" | "server", payload: LogPayload): Promise<LogErrorResult>;
+/**
+ * Wraps a Netlify background handler: intercepts console.log/error/warn
+ * during the invocation, prefixes `[functionName]:`, and flushes to the
+ * `<APP_ENV>/background-functions` stream before returning (so logs are not
+ * lost when Netlify freezes the isolate).
+ */
+export declare function withBackgroundLogs<TEvent, TContext, TResult>(functionName: string, handler: (event: TEvent, context: TContext) => TResult | Promise<TResult>): (event: TEvent, context: TContext) => Promise<TResult>;

package/dist/zauru/cloudwatch-remix.server.d.ts

@@ -0,0 +1,15 @@
+import type { ActionFunction } from "@remix-run/node";
+/**
+ * Remix `handleError` for `entry.server.tsx`. Captures loader/action errors
+ * and sends them to CloudWatch (`<APP_ENV>/server`). Never throws.
+ */
+export declare function handleError(error: unknown, { request }: {
+    request: Request;
+}): Promise<void>;
+/**
+ * Remix action for `POST /api/client-errors`.
+ *
+ * Best-effort: session is optional (errors can happen on /login), but if a
+ * cookie is present the username is attached. Never requires app access.
+ */
+export declare function createClientErrorsAction(): ActionFunction;

package/dist/zauru/cloudwatch.server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-only CloudWatch observability for Remix webapps.
+ *
+ * Import from `@zauru-sdk/utils/cloudwatch.server` (not the main barrel) so
+ * the AWS SDK stays out of the client bundle.
+ */
+export { isCloudWatchEnabled, logError, logEvent, resolveCloudWatchConfig, withBackgroundLogs, type CloudWatchConfigInfo, type LogErrorResult, type LogLevel, type LogOrigin, type LogPayload, } from "./cloudwatch-logger.server.js";
+export { createClientErrorsAction, handleError, } from "./cloudwatch-remix.server.js";

package/dist/zauru/remix-entry.server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Remix 2 SSR entry + CloudWatch `handleError`.
+ *
+ * ```ts
+ * export { handleRequest as default, handleError } from "@zauru-sdk/utils/remix-entry.server";
+ * ```
+ */
+export { handleRequest, handleError } from "./remix-handle-request.server.js";

package/dist/zauru/remix-handle-request.server.d.ts

@@ -0,0 +1,14 @@
+import type { AppLoadContext, EntryContext } from "@remix-run/node";
+import { handleError } from "./cloudwatch-remix.server.js";
+/**
+ * Remix 2 `handleRequest` (pipeable SSR). Use with `handleError` from
+ * `@zauru-sdk/utils/cloudwatch.server` in `app/entry.server.tsx`:
+ *
+ * ```ts
+ * export { handleRequest as default, handleError } from "@zauru-sdk/utils/remix-entry.server";
+ * ```
+ *
+ * Remix 1 apps keep their own `renderToString` entry; they have no `handleError`.
+ */
+export declare function handleRequest(request: Request, responseStatusCode: number, responseHeaders: Headers, remixContext: EntryContext, _loadContext: AppLoadContext): Promise<unknown>;
+export { handleError };

package/package.json

@@ -1,11 +1,38 @@
 {
   "name": "@zauru-sdk/utils",
-  "version": "6.14.0",
+  "version": "6.16.0",
   "description": "Utilidades, parseo de request y demás para desarrollo de webapps de Zauru",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./cloudwatch.server": {
+      "types": "./dist/zauru/cloudwatch.server.d.ts",
+      "import": "./dist/esm/zauru/cloudwatch.server.js",
+      "default": "./dist/esm/zauru/cloudwatch.server.js"
+    },
+    "./remix-entry.server": {
+      "types": "./dist/zauru/remix-entry.server.d.ts",
+      "import": "./dist/esm/zauru/remix-entry.server.js",
+      "default": "./dist/esm/zauru/remix-entry.server.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "cloudwatch.server": [
+        "./dist/zauru/cloudwatch.server.d.ts"
+      ],
+      "remix-entry.server": [
+        "./dist/zauru/remix-entry.server.d.ts"
+      ]
+    }
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -21,14 +48,28 @@
   "author": "Oscar Cuéllar",
   "license": "MIT",
   "peerDependencies": {
-    "react": "^18.2.0 || ^19.0.0"
+    "@remix-run/react": "^2.8.1",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@remix-run/react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@remix-run/react": "^2.8.1",
     "@types/react": "^18.2.20",
+    "@types/react-dom": "^18.2.7",
     "react": "^18.2.0",
+    "react-dom": "^18.2.0",
     "typescript": "^5.1.6"
   },
   "dependencies": {
+    "@aws-sdk/client-cloudwatch-logs": "^3.1123.0",
     "@remix-run/node": "^2.8.1",
     "@zauru-sdk/common": "^6.6.0",
     "@zauru-sdk/config": "^6.0.0",
@@ -37,5 +78,5 @@
     "@zauru-sdk/types": "^6.16.0",
     "moment": "^2.30.1"
   },
-  "gitHead": "b0d95fcc90a6789ba2bf4bdcb0f54070c7583e85"
+  "gitHead": "41f536143a03ddca17bbf467c027ef0179493479"
 }