@kyncode/sdk

SDK oficial de KYNCODE para verificar la conexión de una aplicación y capturar errores de servidor en Next.js y Node.js.

Requiere Node.js 22 o una versión posterior con soporte vigente.

Instalación

Instalalo desde npm en tu aplicación:

npm install @kyncode/sdk

Credencial

Guardá la API key del proyecto como un secreto en la plataforma donde desplegás la aplicación:

KYNCODE_API_KEY=kyn_live_...

No la incluyas en el repositorio, no la expongas al navegador y no uses un nombre público como NEXT_PUBLIC_KYNCODE_API_KEY.

Esa es la única variable necesaria para conectar el SDK. El destino de ingestión es interno, compartido por todas las instalaciones y no debe configurarse en la aplicación del usuario.

Next.js

Creá instrumentation.ts en la raíz de la aplicación, o dentro de src/ si el proyecto utiliza esa estructura:

export { onRequestError, register } from '@kyncode/sdk';

register verifica proactivamente la conexión con KYNCODE cuando inicia el servidor. onRequestError captura los errores globales que Next.js entrega a su instrumentación. El hook registra la entrega en waitUntil cuando el runtime expone un contexto compatible y vuelve apenas queda programada. Si ese contexto no existe, espera un único intento de hasta 2 segundos para respetar el lifecycle de Next.js sin prolongar repetidamente una respuesta fallida. No necesitás crear una ruta en tu aplicación.

Si además querés proteger de forma explícita un Route Handler o una Server Action, podés envolverla con Loly.shield:

import { Loly } from '@kyncode/sdk';

export const POST = Loly.shield(async (request: Request) => {
  return Response.json(await request.json());
});

La instrumentación global suele ser suficiente. Evitá combinarla con Loly.shield sobre el mismo flujo salvo que necesites contexto explícito: el SDK deduplica el mismo error durante 5 segundos, pero mantener una sola estrategia es más simple y predecible.

Node.js

En un proceso Node.js sin framework HTTP, verificá la conexión una vez durante el arranque y protegé explícitamente los trabajos que quieras observar:

import { Loly, type ConnectivityDiagnostic } from '@kyncode/sdk';

const connection: ConnectivityDiagnostic = await Loly.connect('Node.js');
if (!connection.ok) {
  console.warn(`KYNCODE no conectado: ${connection.status} — ${connection.message}`);
}

const runProtectedJob = Loly.shield(async () => {
  // Trabajo de la aplicación.
});

Loly.shield captura el error y vuelve a lanzar exactamente el mismo valor para preservar el comportamiento de la aplicación. Para un servidor HTTP usá el adaptador de su framework.

Loly.connect() siempre devuelve un diagnóstico tipado. status puede ser connected, disabled, failed, invalid_api_key o rate_limited; también incluye el runtime y, cuando corresponde, el status HTTP.

Privacidad y configuración

Los cuerpos de requests y argumentos se excluyen por defecto. Activarlos es una decisión explícita porque pueden contener información sensible:

Loly.init({
  captureBody: true,
});

La sanitización sigue aplicándose, pero no sustituye una política de minimización de datos. También se puede usar KYNCODE_CAPTURE_REQUEST_BODY=true únicamente en el entorno de servidor.

Las URLs se minimizan siempre: el SDK conserva los nombres de los parámetros de query para identificar la forma de la solicitud, pero reemplaza todos sus valores. Códigos OAuth, estados CSRF, OTP, firmas y filtros nunca se incluyen en el evento.

El SDK queda desactivado por defecto cuando NODE_ENV=test; para un test de integración del transporte configurá enabled: true de forma explícita.

Apagado y errores fatales de Node.js

Los adaptadores despachan en segundo plano. Antes de terminar un worker o un servidor, Loly.flush() permite esperar de forma acotada:

const result = await Loly.flush({ timeoutMs: 2_000 });

if (result.timedOut) {
  console.warn(`Quedaron ${result.pending} eventos pendientes`);
}

Para observar fallos fatales del proceso sin impedir que Node finalice con código no cero, registrá el monitor y conservá su función de limpieza:

const stopMonitoring = Loly.listenToProcessEvents();

// Durante un cierre controlado:
stopMonitoring();
await Loly.flush({ timeoutMs: 2_000 });

El monitor no instala un manejador de uncaughtException ni altera la semántica fatal de una excepción no capturada o un rechazo no manejado.

Express

Verificá la conexión al arrancar. Después de las rutas, instalá el middleware de KYNCODE antes de cualquier manejador final de errores propio:

import express from 'express';
import { Loly } from '@kyncode/sdk';

const app = express();

// Definí aquí las rutas de la aplicación.
app.use(Loly.expressErrorHandler());

Al registrar el middleware, KYNCODE verifica la conexión y la captura en segundo plano. Después captura cada error y lo entrega a next(error), por lo que no interrumpe la cadena de manejo de errores de Express.

Fastify

Registrá el manejador global:

import Fastify from 'fastify';
import { Loly } from '@kyncode/sdk';

const fastify = Fastify();

fastify.setErrorHandler(Loly.fastifyErrorHandler());

El manejador verifica la instalación en segundo plano, captura el error y lo envía mediante la respuesta de Fastify. Si la aplicación ya define un setErrorHandler, integrá KYNCODE en una única estrategia global para no reemplazar accidentalmente el comportamiento existente.

Qué hace la conexión proactiva

register, Loly.expressErrorHandler(), Loly.fastifyErrorHandler() y Loly.listenToProcessEvents() verifican automáticamente conectividad y captura al arrancar. Next.js usa intentos breves en paralelo para no prolongar el cold start; los adaptadores Node.js lo hacen en segundo plano. Loly.connect() y Loly.verifyInstallation() siguen disponibles para diagnósticos explícitos. El evento sintético usa el mismo endpoint que los errores reales, pero no crea incidentes ni consume sandboxes.

La señal de conectividad no analiza por sí sola el código ni afirma que no haya vulnerabilidades. Para realizar un inventario o análisis del repositorio también debe existir una fuente de código autorizada en KYNCODE.

Validación y publicación

Desde packages/sdk, un mantenedor puede reproducir la validación completa antes de publicar:

npm ci
npm run release:check
npm run ci:check
npm publish --dry-run

release:check limpia artefactos anteriores, ejecuta el typecheck estricto y los tests, genera ESM y CommonJS con sus declaraciones y source maps, crea el tarball real, lo valida con publint y Are The Types Wrong, y finalmente lo instala en un proyecto temporal que prueba import, require y ambos modos de TypeScript. El mismo tarball también se instala con dependencias fijadas en una aplicación mínima de Next.js 16.3.2, se compila con Turbopack y Webpack, se ejecutan rutas reales en Node y Edge, y se comprueba una entrega real de onRequestError. ci:check repite el proceso desde una copia limpia usando exclusivamente el package-lock.json propio del SDK. Los gates completos forman parte de prepack, por lo que un npm publish directo no los evita; postpack comprueba además que los artefactos ESM y CommonJS recién empaquetados sigan siendo importables y expongan la versión correcta.

El paquete está configurado como scoped público en el registro oficial de npm. La publicación efectiva requiere una sesión npm autorizada para el scope @kyncode:

npm whoami
npm publish

Decisión legal pendiente

La licencia permanece deliberadamente como UNLICENSED. No se debe realizar una publicación pública hasta que KYNCODE autorice su distribución y defina la licencia aplicable. No se agregaron autor, repositorio ni homepage porque esos datos no están confirmados en el proyecto.