@laburen/delta-sdk 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/LICENSE +21 -0
  3. package/README.md +133 -0
  4. package/dist/core/config.d.ts +44 -0
  5. package/dist/core/config.d.ts.map +1 -0
  6. package/dist/core/config.js +163 -0
  7. package/dist/core/config.js.map +1 -0
  8. package/dist/core/constantes.d.ts +15 -0
  9. package/dist/core/constantes.d.ts.map +1 -0
  10. package/dist/core/constantes.js +15 -0
  11. package/dist/core/constantes.js.map +1 -0
  12. package/dist/core/contadores.d.ts +28 -0
  13. package/dist/core/contadores.d.ts.map +1 -0
  14. package/dist/core/contadores.js +53 -0
  15. package/dist/core/contadores.js.map +1 -0
  16. package/dist/core/scrubbing.d.ts +10 -0
  17. package/dist/core/scrubbing.d.ts.map +1 -0
  18. package/dist/core/scrubbing.js +92 -0
  19. package/dist/core/scrubbing.js.map +1 -0
  20. package/dist/core/sesion.d.ts +9 -0
  21. package/dist/core/sesion.d.ts.map +1 -0
  22. package/dist/core/sesion.js +20 -0
  23. package/dist/core/sesion.js.map +1 -0
  24. package/dist/core/sobre.d.ts +46 -0
  25. package/dist/core/sobre.d.ts.map +1 -0
  26. package/dist/core/sobre.js +200 -0
  27. package/dist/core/sobre.js.map +1 -0
  28. package/dist/core/tipos.d.ts +154 -0
  29. package/dist/core/tipos.d.ts.map +1 -0
  30. package/dist/core/tipos.js +6 -0
  31. package/dist/core/tipos.js.map +1 -0
  32. package/dist/core/transporte.d.ts +24 -0
  33. package/dist/core/transporte.d.ts.map +1 -0
  34. package/dist/core/transporte.js +70 -0
  35. package/dist/core/transporte.js.map +1 -0
  36. package/dist/index.d.ts +2 -0
  37. package/dist/index.d.ts.map +1 -0
  38. package/dist/index.js +2 -0
  39. package/dist/index.js.map +1 -0
  40. package/dist/telemetry/captura.d.ts +8 -0
  41. package/dist/telemetry/captura.d.ts.map +1 -0
  42. package/dist/telemetry/captura.js +136 -0
  43. package/dist/telemetry/captura.js.map +1 -0
  44. package/dist/telemetry/index.d.ts +5 -0
  45. package/dist/telemetry/index.d.ts.map +1 -0
  46. package/dist/telemetry/index.js +3 -0
  47. package/dist/telemetry/index.js.map +1 -0
  48. package/dist/telemetry/tipos.d.ts +2 -0
  49. package/dist/telemetry/tipos.d.ts.map +1 -0
  50. package/dist/telemetry/tipos.js +2 -0
  51. package/dist/telemetry/tipos.js.map +1 -0
  52. package/dist/telemetry/with-telemetry.d.ts +18 -0
  53. package/dist/telemetry/with-telemetry.d.ts.map +1 -0
  54. package/dist/telemetry/with-telemetry.js +81 -0
  55. package/dist/telemetry/with-telemetry.js.map +1 -0
  56. package/dist/telemetry/with-tool.d.ts +9 -0
  57. package/dist/telemetry/with-tool.d.ts.map +1 -0
  58. package/dist/telemetry/with-tool.js +20 -0
  59. package/dist/telemetry/with-tool.js.map +1 -0
  60. package/docs/que-se-manda.md +133 -0
  61. package/docs/superficies.md +239 -0
  62. package/docs/telemetria.md +258 -0
  63. package/docs/troubleshooting.md +115 -0
  64. package/package.json +61 -0
  65. package/src/core/config.ts +178 -0
  66. package/src/core/constantes.ts +17 -0
  67. package/src/core/contadores.ts +71 -0
  68. package/src/core/scrubbing.ts +104 -0
  69. package/src/core/sesion.ts +22 -0
  70. package/src/core/sobre.ts +236 -0
  71. package/src/core/tipos.ts +131 -0
  72. package/src/core/transporte.ts +93 -0
  73. package/src/index.ts +7 -0
  74. package/src/telemetry/captura.ts +161 -0
  75. package/src/telemetry/index.ts +16 -0
  76. package/src/telemetry/tipos.ts +13 -0
  77. package/src/telemetry/with-telemetry.ts +128 -0
  78. package/src/telemetry/with-tool.ts +23 -0
@@ -0,0 +1,136 @@
1
+ import { notifyUsable, validar } from "../core/config.js";
2
+ import { contarBeforeSend, contarInterno } from "../core/contadores.js";
3
+ import { aplicarBeforeSend, scrubEvento } from "../core/scrubbing.js";
4
+ import { armarEvento, armarSobre, extraerException, serializarAcotado } from "../core/sobre.js";
5
+ import { AVISO_CTX_ROTO, enviar, probarCtx } from "../core/transporte.js";
6
+ import { crearWithTool } from "./with-tool.js";
7
+ /** Descarta todo, pero `withTool` sigue corriendo la tool y re-lanzando: un cliente inerte no
8
+ * puede cambiar el comportamiento de la app. */
9
+ function clienteInerte() {
10
+ return {
11
+ captureException() { },
12
+ captureEvent() { },
13
+ withTool: crearWithTool(() => { }),
14
+ };
15
+ }
16
+ /** El `notify` de `CaptureOptions` es el camino multi-tenant que lee una fila de D1 en el momento
17
+ * del error, y ahí una columna puede venir NULL — el mismo agujero que la validación de la
18
+ * config, pero por evento. Si el override no es usable se descarta CON AVISO: el evento sale
19
+ * igual, con el `notify` de la config (que ya se validó), en vez de perderse mudo con un 400. */
20
+ function notifyDelEvento(override, notifyDeConfig) {
21
+ if (override === undefined)
22
+ return notifyDeConfig;
23
+ if (notifyUsable(override))
24
+ return override;
25
+ console.error("[delta-sdk] el notify de CaptureOptions no es usable (revisá channel/to): se descarta y el evento sale con el notify de la config");
26
+ return notifyDeConfig;
27
+ }
28
+ /** El núcleo explícito, y el camino principal: los dos wrappers se construyen sobre esto y
29
+ * ninguno puede hacer nada que esto no permita.
30
+ *
31
+ * Va llamado DENTRO de una invocación —`init()` de un Durable Object, un handler— y nunca a
32
+ * nivel de módulo: un valor aleatorio en el scope global hace fallar el deploy. */
33
+ export function createTelemetry(config) {
34
+ let avisado = false;
35
+ // Una vez por cliente y no una por captura: 40 capturas no pueden ser 40 líneas iguales.
36
+ const avisarCtxRoto = () => {
37
+ if (avisado)
38
+ return;
39
+ avisado = true;
40
+ console.error(AVISO_CTX_ROTO);
41
+ };
42
+ // El único punto de estrangulamiento: `validar` lee `service.name`, `organizationId`, `agentId`,
43
+ // `apiKey`, `surface` y `notify` de un `entrada` que puede ser cualquier cosa en runtime — un
44
+ // getter roto en CUALQUIERA de esos campos, o el objeto `config` entero armado como un `Proxy`
45
+ // hostil, puede lanzar antes de llegar al `try/catch` interno de `motivoNotifyInvalido`. Envolver
46
+ // acá cierra el invariante para TODO el objeto de entrada de una sola vez, en vez de una lista de
47
+ // campos que hay que mantener campo por campo.
48
+ let resultado;
49
+ try {
50
+ resultado = validar(config);
51
+ }
52
+ catch (error) {
53
+ console.error("[delta-sdk] no se pudo leer la config: este worker no va a reportar nada", error);
54
+ return clienteInerte();
55
+ }
56
+ if (!resultado.ok) {
57
+ console.error(`[delta-sdk] config inválida: este worker no va a reportar nada. Falta o está vacío: ${resultado.faltan.join(", ")}`);
58
+ return clienteInerte();
59
+ }
60
+ const cfg = resultado.config;
61
+ const ctx = probarCtx(config.ctx, avisarCtxRoto);
62
+ const capturar = (tipo, mensaje, exception, severityDefault, opciones) => {
63
+ try {
64
+ const armado = armarEvento({
65
+ tipo,
66
+ mensaje,
67
+ exception,
68
+ agentId: cfg.agentId,
69
+ surface: cfg.surface,
70
+ severityDefault,
71
+ opciones,
72
+ });
73
+ const limpio = scrubEvento(armado, cfg.scrub);
74
+ const final = aplicarBeforeSend(limpio, cfg.beforeSend);
75
+ if (final === null) {
76
+ // Un null cuenta como drop con razón `before_send`, que es una de las razones
77
+ // canónicas de Sentry.
78
+ contarBeforeSend();
79
+ return;
80
+ }
81
+ const sobre = armarSobre({
82
+ evento: final,
83
+ service: cfg.service,
84
+ // Los overrides por evento: un worker multi-tenant no conoce estos valores
85
+ // cuando se arma el cliente. `||` y no `??`: la config ya se validó no
86
+ // vacía, así que un "" del caller no puede ganarle al fallback bueno.
87
+ organizationId: opciones.organizationId || cfg.organizationId,
88
+ surface: cfg.surface,
89
+ notify: notifyDelEvento(opciones.notify, cfg.notify),
90
+ });
91
+ const { body } = serializarAcotado(sobre);
92
+ enviar({
93
+ body,
94
+ apiKey: cfg.apiKey,
95
+ url: cfg.ingestUrl,
96
+ ctx,
97
+ debug: cfg.debug,
98
+ avisarCtxRoto,
99
+ });
100
+ }
101
+ catch (error) {
102
+ // Última red. La superficie pública entera está envuelta: el SDK no puede lanzar ni
103
+ // con la config más rara. Es la quinta forma de perder un evento, y se
104
+ // cuenta igual que las otras cuatro: sin esto el sobre siguiente reportaba los cuatro
105
+ // contadores en cero, como si nada hubiera pasado.
106
+ contarInterno();
107
+ console.error("[delta-sdk] no se pudo reportar el evento", error);
108
+ }
109
+ };
110
+ /** Devuelve void, nunca una promesa, y nunca lanza. No se puede `await` a propósito:
111
+ * esperarlo le sumaría 40-150 ms a cada respuesta del agente.
112
+ *
113
+ * El try/catch de acá es una red DISTINTA de la de `capturar`: `extraerException` lee
114
+ * `.name`/`.message`/`.stack` de un valor que viene del cliente y que nadie validó, y un
115
+ * getter roto (una lib de source maps, un mock) puede lanzar ahí, antes de que exista ningún
116
+ * evento que meter en la red de `capturar`. Sin esto el throw se escapa de la superficie
117
+ * pública y, peor, `withTool` lo re-lanza a ÉL en vez del error original de la tool. */
118
+ const captureException = (error, opciones = {}) => {
119
+ let exception;
120
+ try {
121
+ exception = extraerException(error);
122
+ }
123
+ catch (fallo) {
124
+ console.error("[delta-sdk] no se pudo leer el error recibido", fallo);
125
+ exception = { type: "UnknownError" };
126
+ }
127
+ capturar("error", exception?.message, exception, "error", opciones);
128
+ };
129
+ /** El default es `warning` y no `error` porque un captureEvent típico registra una falla que
130
+ * el código ya manejó: se guarda en D1 y no despierta a nadie. */
131
+ const captureEvent = (message, opciones = {}) => {
132
+ capturar("event", message, undefined, "warning", opciones);
133
+ };
134
+ return { captureException, captureEvent, withTool: crearWithTool(captureException) };
135
+ }
136
+ //# sourceMappingURL=captura.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"captura.js","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,5 @@
1
+ export { createTelemetry } from "./captura.js";
2
+ export type { CaptureOptions, CtxLike, Envelope, HandlerTelemetryConfig, Notify, RetryInfo, Severity, Surface, TelemetryClient, TelemetryConfig, TelemetryEvent, } from "./tipos.js";
3
+ export type { Handlers } from "./with-telemetry.js";
4
+ export { withTelemetry } from "./with-telemetry.js";
5
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EACX,cAAc,EACd,OAAO,EACP,QAAQ,EACR,sBAAsB,EACtB,MAAM,EACN,SAAS,EACT,QAAQ,EACR,OAAO,EACP,eAAe,EACf,eAAe,EACf,cAAc,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
@@ -0,0 +1,3 @@
1
+ export { createTelemetry } from "./captura.js";
2
+ export { withTelemetry } from "./with-telemetry.js";
3
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAe/C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
@@ -0,0 +1,2 @@
1
+ export type { CaptureOptions, CtxLike, Envelope, HandlerTelemetryConfig, Notify, RetryInfo, Severity, Surface, TelemetryClient, TelemetryConfig, TelemetryEvent, } from "../core/tipos.js";
2
+ //# sourceMappingURL=tipos.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tipos.d.ts","sourceRoot":"","sources":["../../src/telemetry/tipos.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,cAAc,EACd,OAAO,EACP,QAAQ,EACR,sBAAsB,EACtB,MAAM,EACN,SAAS,EACT,QAAQ,EACR,OAAO,EACP,eAAe,EACf,eAAe,EACf,cAAc,GACd,MAAM,kBAAkB,CAAC"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=tipos.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tipos.js","sourceRoot":"","sources":["../../src/telemetry/tipos.ts"],"names":[],"mappings":""}
@@ -0,0 +1,18 @@
1
+ import type { HandlerTelemetryConfig } from "../core/tipos.js";
2
+ /** `(...args: never[]) => unknown` es el supertipo de cualquier función, sin usar `any`: deja
3
+ * pasar el handler tal como lo escribió el implementador, con SUS tipos de Cloudflare. */
4
+ type HandlerCualquiera = (...args: never[]) => unknown;
5
+ export interface Handlers {
6
+ fetch?: HandlerCualquiera;
7
+ queue?: HandlerCualquiera;
8
+ scheduled?: HandlerCualquiera;
9
+ }
10
+ /** Envuelve el `export default` de un worker. Recibe la config como FUNCIÓN de `env` y no como
11
+ * objeto ya armado, porque el `env` no existe a nivel de módulo y evaluar la config ahí sería
12
+ * el mismo error que genera ids en el scope global.
13
+ *
14
+ * Solo ve lo que ESCAPA del handler: un `catch` que loguea y devuelve un valor no deja escapar
15
+ * nada, y el wrapper no se entera. Envolver no reemplaza revisar los `catch` que ya existen. */
16
+ export declare function withTelemetry<Env, H extends Handlers>(configFn: (env: Env) => HandlerTelemetryConfig, handlers: H): H;
17
+ export {};
18
+ //# sourceMappingURL=with-telemetry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"with-telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGX,sBAAsB,EAGtB,MAAM,kBAAkB,CAAC;AAG1B;2FAC2F;AAC3F,KAAK,iBAAiB,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAsFD;;;;;iGAKiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,QAAQ,EACpD,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,sBAAsB,EAC9C,QAAQ,EAAE,CAAC,GACT,CAAC,CAcH"}
@@ -0,0 +1,81 @@
1
+ import { queueMaxRetriesUsable } from "../core/config.js";
2
+ import { createTelemetry } from "./captura.js";
3
+ /** El nombre del handler ES la superficie. No hay nada que el implementador pueda escribir mal,
4
+ * y a diferencia de los comentarios del repo, el nombre del handler no miente. */
5
+ const SUPERFICIE_POR_HANDLER = {
6
+ fetch: "worker",
7
+ queue: "queue",
8
+ scheduled: "cron",
9
+ };
10
+ /** Los números del reintento que el SDK puede leer del runtime. En `queue` salen del batch; en
11
+ * las otras dos superficies los pone el default de la superficie. */
12
+ function opcionesDelHandler(surface, primero, queueMaxRetries) {
13
+ if (surface !== "queue")
14
+ return {};
15
+ const mensajes = primero?.messages ?? [];
16
+ if (mensajes.length === 0)
17
+ return {};
18
+ // Un batch se reintenta ENTERO: el máximo es el intento que puede ser el final. Con el
19
+ // mínimo, la alerta terminal podría no dispararse nunca.
20
+ const attempt = Math.max(...mensajes.map((mensaje) => mensaje.attempts ?? 1));
21
+ // Un batch no tiene un único mensaje del que colgar el id. Para capturar por mensaje va
22
+ // createTelemetry, y está documentado en docs/superficies.md.
23
+ const primerMensaje = mensajes.length === 1 ? mensajes[0] : undefined;
24
+ const workUnitId = primerMensaje?.id ?? null;
25
+ // max_retries son los reintentos DESPUÉS de la primera entrega: limit = max_retries + 1. Si
26
+ // no está, se omite en vez de adivinar.
27
+ return queueMaxRetries === undefined
28
+ ? { retry: { attempt, workUnitId } }
29
+ : { retry: { attempt, limit: queueMaxRetries + 1, workUnitId } };
30
+ }
31
+ function envolver(surface, configFn, handler) {
32
+ return async (primero, env, ctx) => {
33
+ let cliente = null;
34
+ let cfg = null;
35
+ try {
36
+ cfg = configFn(env);
37
+ // `surface` y `ctx` los pone el wrapper: el tipo se los prohíbe al implementador para
38
+ // que no pueda pisarlos con un valor equivocado.
39
+ const { surface: _surface, ctx: _ctx, ...resto } = cfg;
40
+ cliente = createTelemetry({ ...resto, surface, ctx });
41
+ }
42
+ catch (error) {
43
+ // Si la telemetría no arranca, el handler del cliente corre igual.
44
+ console.error("[delta-sdk] no se pudo inicializar la telemetría; el handler sigue igual", error);
45
+ }
46
+ try {
47
+ return await handler(primero, env, ctx);
48
+ }
49
+ catch (error) {
50
+ // `cfg` es la config CRUDA que devolvió `configFn`, no la `ConfigValidada` de
51
+ // `createTelemetry`: este camino no pasa por `validar`, así que hay que sanearlo acá
52
+ // también. El aviso de un valor inválido ya lo emite `createTelemetry` más arriba,
53
+ // al validar la misma config para construir `cliente`.
54
+ const queueMaxRetriesCrudo = cfg?.queueMaxRetries;
55
+ const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
56
+ ? queueMaxRetriesCrudo
57
+ : undefined;
58
+ cliente?.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
59
+ // Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
60
+ // decidir el 500 o el reintento del batch.
61
+ throw error;
62
+ }
63
+ };
64
+ }
65
+ /** Envuelve el `export default` de un worker. Recibe la config como FUNCIÓN de `env` y no como
66
+ * objeto ya armado, porque el `env` no existe a nivel de módulo y evaluar la config ahí sería
67
+ * el mismo error que genera ids en el scope global.
68
+ *
69
+ * Solo ve lo que ESCAPA del handler: un `catch` que loguea y devuelve un valor no deja escapar
70
+ * nada, y el wrapper no se entera. Envolver no reemplaza revisar los `catch` que ya existen. */
71
+ export function withTelemetry(configFn, handlers) {
72
+ const salida = { ...handlers };
73
+ for (const nombre of ["fetch", "queue", "scheduled"]) {
74
+ const handler = handlers[nombre];
75
+ if (handler === undefined)
76
+ continue;
77
+ salida[nombre] = envolver(SUPERFICIE_POR_HANDLER[nombre], configFn, handler);
78
+ }
79
+ return salida;
80
+ }
81
+ //# sourceMappingURL=with-telemetry.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"with-telemetry.js","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,9 @@
1
+ import type { CaptureOptions, TelemetryClient } from "../core/tipos.js";
2
+ /** Envuelve una tool de MCP. El implementador NO escribe captureException en ninguna tool: lo
3
+ * hace este wrapper, una vez, para todas las que envuelva. Ese es el aporte.
4
+ *
5
+ * Tres requisitos, no sugerencias: reenvía TODOS los argumentos porque el SDK invoca con
6
+ * `(args, extra)`; re-lanza EL MISMO objeto de error porque su mensaje es el que ve el usuario
7
+ * final; y es arrow function para no introducir un `this` propio. */
8
+ export declare function crearWithTool(capturar: (error: unknown, opciones: CaptureOptions) => void): TelemetryClient["withTool"];
9
+ //# sourceMappingURL=with-tool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"with-tool.d.ts","sourceRoot":"","sources":["../../src/telemetry/with-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;;;sEAKsE;AACtE,wBAAgB,aAAa,CAC5B,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,GAC1D,eAAe,CAAC,UAAU,CAAC,CAY7B"}
@@ -0,0 +1,20 @@
1
+ /** Envuelve una tool de MCP. El implementador NO escribe captureException en ninguna tool: lo
2
+ * hace este wrapper, una vez, para todas las que envuelva. Ese es el aporte.
3
+ *
4
+ * Tres requisitos, no sugerencias: reenvía TODOS los argumentos porque el SDK invoca con
5
+ * `(args, extra)`; re-lanza EL MISMO objeto de error porque su mensaje es el que ve el usuario
6
+ * final; y es arrow function para no introducir un `this` propio. */
7
+ export function crearWithTool(capturar) {
8
+ return (nombre, fn) => async (...args) => {
9
+ try {
10
+ return await fn(...args);
11
+ }
12
+ catch (error) {
13
+ // El reporte vive acá y en ningún otro lado. Y solo llega si `fn` LANZA: una tool
14
+ // que atrapa su propio error y devuelve un valor no pasa por acá.
15
+ capturar(error, { workUnit: nombre });
16
+ throw error;
17
+ }
18
+ };
19
+ }
20
+ //# sourceMappingURL=with-tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"with-tool.js","sourceRoot":"","sources":["../../src/telemetry/with-tool.ts"],"names":[],"mappings":"AAEA;;;;;sEAKsE;AACtE,MAAM,UAAU,aAAa,CAC5B,QAA4D;IAE5D,OAAO,CAA4B,MAAc,EAAE,EAAqC,EAAE,EAAE,CAC3F,KAAK,EAAE,GAAG,IAAU,EAAc,EAAE;QACnC,IAAI,CAAC;YACJ,OAAO,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,kFAAkF;YAClF,kEAAkE;YAClE,QAAQ,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YACtC,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,133 @@
1
+ # Qué se manda: el contrato con la ingesta
2
+
3
+ Esta página describe el sobre (`Envelope`) que el SDK arma y manda a `telemetry.laburen.com/events`,
4
+ los formatos exactos de cada campo, y la división de trabajo entre el SDK y la ingesta.
5
+
6
+ ## 1. El payload de ejemplo
7
+
8
+ ```json
9
+ {
10
+ "sdk": { "name": "@laburen/delta-sdk", "version": "1.0.0" },
11
+ "sent_at": "2026-07-30T18:22:10.200Z",
12
+ "drops": { "incompletos": 0, "fallados": 0, "before_send": 0, "recortados": 0, "internos": 0 },
13
+ "session": "1a08cf9c",
14
+ "resource": {
15
+ "service": { "name": "mi-mcp", "version": "1.0.0", "environment": "production" },
16
+ "client": { "organization_id": "org_ejemplo" },
17
+ "surface": "durable_object"
18
+ },
19
+ "notify": { "slack": { "enabled": true, "channel": "C00000000000" } },
20
+ "events": [{
21
+ "event_id": "9f8c1e2a-1b3d-4a5c-9e6f-7a8b9c0d1e2f",
22
+ "seq": 17,
23
+ "timestamp": "2026-07-30T18:22:10.123Z",
24
+ "type": "error",
25
+ "severity": "error",
26
+ "message": "mi_tool falló al renovar el token",
27
+ "context": { "agent_id": "agent_ejemplo", "work_unit": "mi_tool", "trace_id": "tr_9f3c..." },
28
+ "retry": { "attempt": 1, "limit": 1, "is_final_attempt": true, "work_unit_id": null },
29
+ "exception": { "type": "Error", "message": "Token no disponible", "stacktrace": "…" }
30
+ }]
31
+ }
32
+ ```
33
+
34
+ > El campo `drops` lleva **cinco** contadores (`incompletos`, `fallados`, `before_send`,
35
+ > `recortados`, `internos` — sección 4), no dos: son las cinco formas en que un evento puede no
36
+ > llegar completo a D1.
37
+
38
+ ## 2. Formatos exactos
39
+
40
+ | Campo | Formato |
41
+ |---|---|
42
+ | `event_id` | UUID v4, **en minúsculas** |
43
+ | `timestamp`, `sent_at` | ISO 8601 UTC, **con milisegundos y `Z`** |
44
+ | `seq` | entero **≥ 1** |
45
+ | `type` | `"error"` \| `"event"` |
46
+ | `severity` | `"debug"` \| `"info"` \| `"warning"` \| `"error"` \| `"fatal"` |
47
+ | `surface` | uno de los seis de `docs/superficies.md`: `worker`, `durable_object`, `workflow`, `queue`, `alarm`, `cron` |
48
+ | `channel` (dentro de `notify`) | `/^[CGD][A-Z0-9]{8,}$/` — un id de canal de Slack real |
49
+
50
+ `new Date().toISOString()` produce exactamente el formato ISO 8601 UTC con milisegundos y `Z` que se
51
+ pide. `crypto.randomUUID()` produce un UUID v4 en minúsculas. **El SDK no formatea nada a mano**: usa
52
+ estas dos funciones del runtime tal cual.
53
+
54
+ ## 3. `session` + `seq`: para qué sirven, y su límite honesto
55
+
56
+ `session` identifica al isolate (se genera una vez, la primera vez que hace falta, y no cambia
57
+ mientras el isolate viva). `seq` es un contador que arranca en 1 y sube de a uno por cada evento de
58
+ esa sesión, y **nunca se reinicia**.
59
+
60
+ Juntos le permiten a la ingesta notar que faltó algo: si llegan los `seq` 1, 2 y 4 de la misma
61
+ `session`, la ingesta sabe que el 3 **existió y se perdió** en algún punto del camino.
62
+
63
+ **El límite honesto:** este mecanismo detecta huecos **en el medio** de una secuencia, no una **cola
64
+ cortada al final**. Si el isolate muere de golpe después de mandar el `seq` 4, y los envíos 5, 6 y 7
65
+ nunca llegaron a salir del todo, la ingesta solo ve hasta el 4 — no tiene forma de saber que el 5, el
66
+ 6 y el 7 alguna vez existieron. `session` y `seq` prueban huecos, no el tamaño real de lo que se
67
+ perdió al final.
68
+
69
+ ## 4. Los cinco contadores de `drops`
70
+
71
+ | Contador | Qué es |
72
+ |---|---|
73
+ | `incompletos` | `disparados − completados − fallados`: envíos que se dispararon y **no** terminaron ni con éxito ni con una excepción de red — quedaron a mitad de camino porque el isolate murió antes de que el `fetch` resolviera, **o siguen en vuelo** (ver el límite honesto más abajo) |
74
+ | `fallados` | envíos donde el `fetch` mismo lanzó (problema de red o DNS) |
75
+ | `before_send` | eventos descartados porque `beforeSend` devolvió `null` |
76
+ | `recortados` | sobres que hubo que recortar para entrar en el tope de 512 KB (ver sección 5) |
77
+ | `internos` | eventos que se perdieron porque algo entre armar el evento y mandarlo lanzó una excepción (por ejemplo, un `attributes` con un getter roto) — la única razón sin una causa de negocio detrás |
78
+
79
+ **El límite honesto de `incompletos`: mezcla "en vuelo" con "perdido", y en un sobre suelto no se
80
+ puede leer como pérdida.** El `drops` de un sobre es un snapshot tomado en `armarSobre`, **antes**
81
+ de que el `enviar` de ESE MISMO evento termine. Con varias capturas seguidas en la misma invocación,
82
+ cada sobre ve los envíos anteriores todavía pendientes: `incompletos` sube de 0 a 1 a 2 sin que se
83
+ haya perdido nada, porque esos POST siguen en vuelo, no fallaron. **Por eso `incompletos` solo sirve
84
+ agregado sobre muchos isolates**, donde ese sesgo del último evento en vuelo se promedia y lo que
85
+ queda es la señal real de pérdida por ciclo de vida. Mirado así — en agregado, no sobre un sobre
86
+ individual — es el número que decide si hace falta poner una cola de Cloudflare Queues delante de la
87
+ ingesta, en vez de discutirlo por intuición: si `incompletos` es consistentemente ~0, el POST directo
88
+ alcanza; si no, hay pérdida real que una cola resolvería.
89
+
90
+ ## 5. Los límites, y quién los aplica
91
+
92
+ | Límite | Valor | Quién lo aplica |
93
+ |---|---|---|
94
+ | `stacktrace` | 8 KB | los dos lados: el SDK trunca antes de mandar, la ingesta trunca de nuevo del lado servidor |
95
+ | `message` (y `exception.message`) | 2 KB | los dos lados |
96
+ | claves de `attributes` | primeras 64 | los dos lados |
97
+ | cuerpo del sobre completo | 512 KB | **solo el cliente recorta.** El servidor **no trunca** este límite: lo rechaza directo con `413` |
98
+
99
+ Que los dos lados trunquen los primeros tres límites no es redundancia inútil: el cliente lo hace
100
+ para no perder el sobre entero antes de mandarlo, la ingesta lo hace de nuevo para no confiar en que
101
+ el cliente lo haya hecho bien.
102
+
103
+ **El tope de 512 KB del cuerpo es distinto: no se trunca del lado servidor, se rechaza con `413`.**
104
+ Por eso el SDK tiene que recortar **antes** de mandar. El SDK **nunca descarta un evento por ser
105
+ grande**: si el JSON serializado supera el tope, recorta en pasos (primero el `stacktrace` a 1 KB,
106
+ después lo borra del todo, después vacía `attributes`, y por último recorta el `message` a 256
107
+ caracteres), deteniéndose apenas el sobre entra en el tope. El evento siempre sale, aunque llegue con
108
+ menos detalle.
109
+
110
+ ## 6. Los códigos de respuesta reales
111
+
112
+ | Código | Cuándo | Qué hace el SDK |
113
+ |---|---|---|
114
+ | `200` | guardado (con `{accepted, duplicates, alerted, throttled}`) | nada |
115
+ | `400` | payload inválido, o más de 100 eventos por sobre | **no reintenta.** Con `debug: true`, un `console.warn` |
116
+ | `401` | bearer inválido | **no reintenta.** `console.error` siempre, con o sin `debug` — es config rota y hay que verla |
117
+ | `413` | cuerpo > 512 KB | **no reintenta.** No debería pasar si el SDK recorta bien — ver `docs/troubleshooting.md` |
118
+ | `503` | falló D1, o una excepción no manejada en la ingesta | **no reintenta.** Con `debug: true`, un `console.warn` |
119
+
120
+ **El SDK no reintenta en ninguno de estos casos.** Cualquier respuesta —éxito o error— cuenta como
121
+ `completado`, nunca como `fallado` (`fallado` es solo cuando el `fetch` mismo lanza, por red o DNS).
122
+
123
+ ## 7. Additive-only, y el orden de deploy
124
+
125
+ **El contrato es additive-only:** se agregan campos opcionales, nunca se renombra ni se saca nada.
126
+ La ingesta ignora los campos que no conoce, así que un worker con una versión vieja del SDK sigue
127
+ funcionando indefinidamente.
128
+
129
+ **El orden de deploy importa, y es siempre el mismo: la ingesta va antes que el paquete.** Los enums
130
+ de `type`, `severity` y `surface` son **cerrados** del lado de la ingesta: un valor que la ingesta no
131
+ reconoce todavía se rechaza con `400`. Si una versión nueva del SDK agrega un valor a alguno de esos
132
+ enums, la ingesta que lo va a aceptar tiene que estar en producción **antes** de que ese SDK se
133
+ publique — al revés, esos eventos se pierden con `400` en vez de guardarse.