@kyncode/sdk 0.1.0

package/README.md

@@ -0,0 +1,231 @@
+# @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:
+
+```bash
+npm install @kyncode/sdk
+```
+
+## Credencial
+
+Guardá la API key del proyecto como un secreto en la plataforma donde desplegás
+la aplicación:
+
+```text
+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:
+
+```ts
+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`:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+import express from 'express';
+import { Loly } from '@kyncode/sdk';
+
+const app = express();
+
+await Loly.connect('Express');
+
+// Definí aquí las rutas de la aplicación.
+app.use(Loly.expressErrorHandler());
+```
+
+El middleware captura el error y luego lo entrega a `next(error)`, por lo que no
+interrumpe la cadena de manejo de errores de Express.
+
+## Fastify
+
+Verificá la conexión al arrancar y registrá el manejador global:
+
+```ts
+import Fastify from 'fastify';
+import { Loly } from '@kyncode/sdk';
+
+const fastify = Fastify();
+
+await Loly.connect('Fastify');
+fastify.setErrorHandler(Loly.fastifyErrorHandler());
+```
+
+El manejador 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` y `Loly.connect()` envían una señal de conectividad durante el
+arranque. `register` realiza un único intento con un límite corto para no
+prolongar el cold start de Next.js; `Loly.connect()` mantiene los reintentos y el
+diagnóstico completo para verificaciones explícitas. La señal confirma que la
+credencial está configurada y que la aplicación puede comunicarse con KYNCODE
+sin esperar a que ocurra un error.
+
+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:
+
+```bash
+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`:
+
+```bash
+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.