@laburen/delta-sdk 1.1.0 → 1.3.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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,88 @@ Formato: [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/).
4
4
  El paquete es **additive-only**: se agregan funciones y campos opcionales, nunca se renombra ni se
5
5
  saca nada. Un worker que se queda en una versión vieja sigue funcionando.
6
6
 
7
+ ## [1.3.0] — 2026-08-05
8
+
9
+ Solo documentación. **El código no cambió**: si ya estás en `1.2.0`, actualizar es opcional. Es una
10
+ reestructuración de la documentación para que el paquete deje de leerse como "el paquete de
11
+ telemetría" y pase a leerse como lo que es: un paquete con **puertas** (`exports` map), hoy con una
12
+ sola (`/telemetry`) y la raíz preparada para sumar más de forma aditiva.
13
+
14
+ ### Cambiado
15
+
16
+ - El README ya no arranca describiendo `/telemetry`: ahora presenta el paquete y sus puertas
17
+ primero, con una tabla que lista cada una y a dónde va. El quickstart de `/telemetry` (los tres
18
+ casos de uso) se queda en el README, igual que antes, solo que enmarcado como el quickstart de esa
19
+ puerta.
20
+ - Lo transversal a cualquier puerta (instalar, la API key como secret, el `ctx` original del
21
+ handler, qué puerta usar) se juntó en un archivo nuevo, corto: `docs/empezar.md`.
22
+ - `docs/troubleshooting.md` se dividió en dos: los síntomas que valen para cualquier puerta se
23
+ quedan ahí, y los propios de `/telemetry` (`413`, los dos límites del scrubbing, la semántica de
24
+ captura de un `catch` que devuelve un valor) se movieron a `docs/telemetry/troubleshooting.md`
25
+ (nuevo). Cada uno de los dos archivos funciona solo, con un puntero al otro.
26
+ - `docs/superficies.md` no se movió: sigue siendo compartido entre puertas.
27
+
28
+ ### Hay que hacer algo
29
+
30
+ **Los paths de la documentación cambiaron.** Si tenías un link guardado o una lista de lectura
31
+ apuntando a los paths viejos, actualizala:
32
+
33
+ | Path viejo | Path nuevo |
34
+ |---|---|
35
+ | `docs/telemetria.md` | `docs/telemetry/guia.md` |
36
+ | `docs/que-se-manda.md` | `docs/telemetry/que-se-manda.md` |
37
+ | `docs/troubleshooting.md` (síntomas de `413` y de scrubbing) | `docs/telemetry/troubleshooting.md` |
38
+ | `docs/troubleshooting.md` (el resto de los síntomas) | sigue en `docs/troubleshooting.md` |
39
+ | `docs/superficies.md` | sigue en `docs/superficies.md` |
40
+ | — | `docs/empezar.md` (nuevo) |
41
+
42
+ ## [1.2.0] — 2026-08-05
43
+
44
+ `withTelemetry` ahora manda `context.work_unit` con el nombre del handler (`"fetch"`, `"queue"` o
45
+ `"scheduled"`) en la captura automática de lo que escapa de un handler envuelto. Antes ese campo
46
+ salía vacío; `withTool` ya lo mandaba con el nombre de la tool, y esto cierra la misma idea para el
47
+ otro wrapper.
48
+
49
+ ### Agregado
50
+
51
+ - Un error que escapa de `fetch`, `queue` o `scheduled` —los tres handlers que envuelve
52
+ `withTelemetry`— ahora llega con `context.work_unit` igual al nombre del handler. En `queue`
53
+ convive con el bloque `retry` que ya se mandaba: los dos van en el mismo evento, ninguno pisa al
54
+ otro. Una captura manual hecha por el consumidor con su propio `workUnit` —con el cliente del
55
+ cuarto argumento, o dentro de un `catch` propio— sigue ganando: este default solo aplica a la
56
+ captura automática del wrapper.
57
+
58
+ ### Hay que hacer algo
59
+
60
+ Si tenías una alerta o un dashboard armado sobre los eventos que reporta `withTelemetry` cuando
61
+ escapa un error de `fetch`, `queue` o `scheduled`, esos eventos van a **agrupar distinto** que
62
+ antes: la ingesta calcula el fingerprint a partir del evento completo, y sin `work_unit` todos los
63
+ escapes de un mismo worker caían en la misma bolsa. Con el campo puesto, cada entrypoint agrupa por
64
+ separado. Es una mejora, pero es un cambio observable — revisá esa alerta o ese dashboard después
65
+ de actualizar.
66
+
67
+ ## [1.1.1] — 2026-08-04
68
+
69
+ Solo documentación. **El código no cambió**: si ya estás en `1.1.0`, actualizar es opcional.
70
+
71
+ ### Cambiado
72
+
73
+ - `docs/superficies.md` ahora explica **cómo leer los números del reintento en `surface: "workflow"`**:
74
+ que el callback de `step.do` recibe el contexto del step **como parámetro** (no está en `this`), con
75
+ la forma real del objeto, y que **los valores van tal cual, sin sumarle 1** — en `workflow` el
76
+ `limit` de la config **es el total de intentos**, al revés que en `queue`. Sumar 1 ahí haría que el
77
+ intento final nunca quede marcado como definitivo.
78
+ - Queda documentado un borde del runtime: un step que **se cuelga** y es cancelado por el runtime se
79
+ reintenta **por encima** del `limit` configurado, así que el evento del intento que iguala al `limit`
80
+ puede decir `is_final_attempt: true` con otro intento todavía por venir. Con la salida recomendada
81
+ para ese caso: mandar `attempt` y omitir `limit`.
82
+
83
+ ### Hay que hacer algo
84
+
85
+ Nada. Pero si instrumentaste un Workflow y no estabas mandando `retry` porque no encontrabas de dónde
86
+ salían los números, ahora está escrito: son `ctx.attempt` y `ctx.config.retries?.limit` del callback
87
+ del step.
88
+
7
89
  ## [1.1.0] — 2026-08-04
8
90
 
9
91
  `withTelemetry` ahora le pasa el cliente de telemetría al handler. Es aditivo: no rompe ningún
package/README.md CHANGED
@@ -1,31 +1,35 @@
1
1
  # @laburen/delta-sdk
2
2
 
3
- *Sirve para cualquier worker, MCP o workflow de Cloudflare.
3
+ **Sirve para cualquier worker, MCP o workflow de Cloudflare.**
4
4
 
5
- Le manda los errores de tu worker a la ingesta de telemetría (`telemetry.laburen.com`), que los
6
- guarda en D1 y avisa por Slack al canal del cliente.
5
+ El paquete de Laburen para instrumentar workers de Cloudflare, sin dependencias de runtime. Está
6
+ organizado en **puertas**: cada una es un `import` distinto para un propósito distinto, todas
7
+ conviviendo en el mismo paquete.
7
8
 
8
- ```bash
9
- npm i @laburen/delta-sdk
10
- ```
9
+ ## Puertas
11
10
 
12
- Necesitás una API key en el env del worker, como **secret** y nunca como `var`:
11
+ | Puerta | Para qué |
12
+ |---|---|
13
+ | `@laburen/delta-sdk` | la raíz: solo los tipos compartidos entre puertas (`Envelope`, `Notify`, `Severity`, `Surface`, `TelemetryEvent`) — sin runtime |
14
+ | [`@laburen/delta-sdk/telemetry`](#telemetry) | le manda los errores y eventos de tu worker a la ingesta de telemetría (`telemetry.laburen.com`), que los guarda en D1 y avisa por Slack al canal del cliente |
13
15
 
14
- ```bash
15
- wrangler secret put LABUREN_TELEMETRY_KEY
16
- ```
16
+ Instalar el paquete, la API key y el `ctx` son iguales para cualquier puerta: ver
17
+ [docs/empezar.md](docs/empezar.md).
18
+
19
+ ## `telemetry`
20
+
21
+ Le manda los errores de tu worker a la ingesta de telemetría (`telemetry.laburen.com`), que los
22
+ guarda en D1 y avisa por Slack al canal del cliente.
17
23
 
18
- ## Lo que tenés que saber antes de empezar
24
+ ### Lo que tenés que saber antes de empezar
19
25
 
20
26
  - **`captureException` nunca lanza y no se puede `await`.** Un cliente de telemetría no puede
21
27
  romper la app que observa.
22
28
  - **No hay reintentos.** Si la ingesta está caída, el evento se descarta y se cuenta.
23
29
  - **Los wrappers solo ven lo que ESCAPA de la función que envuelven.** Si tu `catch` loguea y
24
- devuelve un valor, el wrapper no se entera. Ver [docs/telemetria.md](docs/telemetria.md).
25
- - **Pasale el `ctx` original del handler**, no una copia hecha con spread. Ver
26
- [docs/troubleshooting.md](docs/troubleshooting.md).
30
+ devuelve un valor, el wrapper no se entera. Ver [docs/telemetry/guia.md](docs/telemetry/guia.md).
27
31
 
28
- ## Caso 1 — MCP en un Durable Object (el 80% del uso)
32
+ ### Caso 1 — MCP en un Durable Object (el 80% del uso)
29
33
 
30
34
  ```ts
31
35
  import { createTelemetry } from "@laburen/delta-sdk/telemetry";
@@ -73,9 +77,9 @@ export class MiAgenteMCP extends McpAgent<Env> {
73
77
  > `fetch` que rutea hacia el Durable Object, el framework de MCP atrapa el error de la tool y lo
74
78
  > convierte en un resultado con `isError: true` antes de que llegue ahí: envolver el `export default`
75
79
  > no reportaría nada. Acá va `createTelemetry` + `withTool`, y nada más. Ver
76
- > [docs/telemetria.md](docs/telemetria.md).
80
+ > [docs/telemetry/guia.md](docs/telemetry/guia.md).
77
81
 
78
- ## Caso 2 — Worker plano, cola y cron
82
+ ### Caso 2 — Worker plano, cola y cron
79
83
 
80
84
  ```ts
81
85
  import { withTelemetry } from "@laburen/delta-sdk/telemetry";
@@ -101,12 +105,12 @@ La config **no lleva `surface`**: se deduce del nombre del handler, y pasarla no
101
105
 
102
106
  **El cuarto argumento (`telemetry`) es el mismo cliente que usa el wrapper.** Un handler que
103
107
  declara solo tres lo ignora y sigue andando igual; uno que lo declara puede usarlo en su propio
104
- `catch` sin llamar a `createTelemetry` de nuevo. Ver [docs/telemetria.md](docs/telemetria.md).
108
+ `catch` sin llamar a `createTelemetry` de nuevo. Ver [docs/telemetry/guia.md](docs/telemetry/guia.md).
105
109
 
106
110
  > **Los nombres de las env var no están estandarizados entre proyectos.** Abrí tu `env.d.ts` antes
107
111
  > de copiar los nombres: no asumas que son los mismos que en otro worker.
108
112
 
109
- ## Caso 3 — Un error que nunca fue una excepción
113
+ ### Caso 3 — Un error que nunca fue una excepción
110
114
 
111
115
  Es el caso más común en los repos que ya existen: `if (!res.ok) { log; return null }`. No hay nada
112
116
  que pasarle a `captureException`, así que va `captureEvent`.
@@ -128,10 +132,12 @@ un grupo nuevo y el dedup de la ingesta no sirve.
128
132
 
129
133
  | Archivo | Para qué |
130
134
  |---|---|
131
- | [docs/telemetria.md](docs/telemetria.md) | la guía larga: config campo por campo, `CaptureOptions`, scrubbing, `beforeSend` |
132
- | [docs/superficies.md](docs/superficies.md) | qué cambia entre worker, durable object, workflow, queue, alarm y cron |
133
- | [docs/que-se-manda.md](docs/que-se-manda.md) | el contrato en prosa, con un payload de ejemplo |
134
- | [docs/troubleshooting.md](docs/troubleshooting.md) | "no llega nada", error 1042, 401, 413, "el worker no deploya" |
135
+ | [docs/empezar.md](docs/empezar.md) | instalar, la API key, el `ctx`, y qué puerta usar — transversal a cualquier puerta |
136
+ | [docs/superficies.md](docs/superficies.md) | qué cambia entre worker, durable object, workflow, queue, alarm y cron — transversal a cualquier puerta |
137
+ | [docs/troubleshooting.md](docs/troubleshooting.md) | "no llega nada", error 1042, 401, "el worker no deploya" — síntomas compartidos por cualquier puerta |
138
+ | [docs/telemetry/guia.md](docs/telemetry/guia.md) | la guía larga de `/telemetry`: config campo por campo, `CaptureOptions`, scrubbing, `beforeSend` |
139
+ | [docs/telemetry/que-se-manda.md](docs/telemetry/que-se-manda.md) | el contrato de `/telemetry` en prosa, con un payload de ejemplo |
140
+ | [docs/telemetry/troubleshooting.md](docs/telemetry/troubleshooting.md) | síntomas propios de `/telemetry`: 413, los límites del scrubbing |
135
141
 
136
142
  El TypeScript real está en `node_modules/@laburen/delta-sdk/src/`: si algo no cierra, se lee.
137
143
 
@@ -3,7 +3,7 @@
3
3
  export declare const INGEST_URL = "https://telemetry.laburen.com/events";
4
4
  export declare const SDK_NAME = "@laburen/delta-sdk";
5
5
  /** Tiene que coincidir con `version` del package.json; lo verifica `npm run version:check`. */
6
- export declare const SDK_VERSION = "1.1.0";
6
+ export declare const SDK_VERSION = "1.3.0";
7
7
  /** Los mismos topes que aplica la ingesta. El cliente los aplica para no perder el sobre entero;
8
8
  * la ingesta, para no confiar en el cliente. */
9
9
  export declare const LIMITES: {
@@ -3,7 +3,7 @@
3
3
  export const INGEST_URL = "https://telemetry.laburen.com/events";
4
4
  export const SDK_NAME = "@laburen/delta-sdk";
5
5
  /** Tiene que coincidir con `version` del package.json; lo verifica `npm run version:check`. */
6
- export const SDK_VERSION = "1.1.0";
6
+ export const SDK_VERSION = "1.3.0";
7
7
  /** Los mismos topes que aplica la ingesta. El cliente los aplica para no perder el sobre entero;
8
8
  * la ingesta, para no confiar en el cliente. */
9
9
  export const LIMITES = {
@@ -189,7 +189,7 @@ export function serializarAcotado(sobre) {
189
189
  }
190
190
  // No cambia la política —no se descarta el evento, no se agregan pasos—, solo deja de ser
191
191
  // mudo: el exceso vive en un campo que ningún paso toca (`fingerprint`, un identificador
192
- // gigantesco), y la ingesta lo va a rechazar con 413 (docs/troubleshooting.md).
192
+ // gigantesco), y la ingesta lo va a rechazar con 413 (docs/telemetry/troubleshooting.md).
193
193
  const bytesFinales = bytesDe(body);
194
194
  if (bytesFinales > LIMITES.bodyBytes) {
195
195
  console.error(`[delta-sdk] el sobre sigue arriba del tope de ${LIMITES.bodyBytes} bytes después de recortar (${bytesFinales} bytes); la ingesta lo va a rechazar con 413`);
@@ -1 +1 @@
1
- {"version":3,"file":"sobre.js","sourceRoot":"","sources":["../../src/core/sobre.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"sobre.js","sourceRoot":"","sources":["../../src/core/sobre.ts"],"names":[],"mappings":"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"}
@@ -1 +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;AA6BD;;;6FAG6F;AAC7F,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACrE,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,GACxD,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,GAC7B,CAAC,GACF,CAAC,CAAC;AAEL,KAAK,iBAAiB,CAAC,CAAC,SAAS,QAAQ,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AA6E3F;;;;;iGAKiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,QAAQ,EACpD,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,sBAAsB,EAC9C,QAAQ,EAAE,CAAC,GACT,iBAAiB,CAAC,CAAC,CAAC,CActB"}
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;AA6BD;;;6FAG6F;AAC7F,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACrE,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,GACxD,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,GAC7B,CAAC,GACF,CAAC,CAAC;AAEL,KAAK,iBAAiB,CAAC,CAAC,SAAS,QAAQ,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAqF3F;;;;;iGAKiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,QAAQ,EACpD,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,sBAAsB,EAC9C,QAAQ,EAAE,CAAC,GACT,iBAAiB,CAAC,CAAC,CAAC,CAetB"}
@@ -7,14 +7,17 @@ const SUPERFICIE_POR_HANDLER = {
7
7
  queue: "queue",
8
8
  scheduled: "cron",
9
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) {
10
+ /** Las opciones de la captura automática: SIEMPRE lleva `workUnit` con el nombre del handler
11
+ * (`"fetch"`, `"queue"` o `"scheduled"`) — es el mismo rol que cumple `withTool(nombre)`, y dice
12
+ * qué entrypoint falló, algo que la superficie (que ya viaja en su propio campo del sobre) no
13
+ * dice por sí sola. Además, en `queue`, suma los números del reintento que el SDK puede leer del
14
+ * batch; en las otras dos superficies los pone el default de la superficie. */
15
+ function opcionesDelHandler(nombre, surface, primero, queueMaxRetries) {
13
16
  if (surface !== "queue")
14
- return {};
17
+ return { workUnit: nombre };
15
18
  const mensajes = primero?.messages ?? [];
16
19
  if (mensajes.length === 0)
17
- return {};
20
+ return { workUnit: nombre };
18
21
  // Un batch se reintenta ENTERO: el máximo es el intento que puede ser el final. Con el
19
22
  // mínimo, la alerta terminal podría no dispararse nunca.
20
23
  const attempt = Math.max(...mensajes.map((mensaje) => mensaje.attempts ?? 1));
@@ -25,10 +28,10 @@ function opcionesDelHandler(surface, primero, queueMaxRetries) {
25
28
  // max_retries son los reintentos DESPUÉS de la primera entrega: limit = max_retries + 1. Si
26
29
  // no está, se omite en vez de adivinar.
27
30
  return queueMaxRetries === undefined
28
- ? { retry: { attempt, workUnitId } }
29
- : { retry: { attempt, limit: queueMaxRetries + 1, workUnitId } };
31
+ ? { workUnit: nombre, retry: { attempt, workUnitId } }
32
+ : { workUnit: nombre, retry: { attempt, limit: queueMaxRetries + 1, workUnitId } };
30
33
  }
31
- function envolver(surface, configFn, handler) {
34
+ function envolver(nombre, surface, configFn, handler) {
32
35
  return async (primero, env, ctx) => {
33
36
  // Nunca queda en `null`: si `configFn` lanza, el handler recibe igual el cliente inerte
34
37
  // como cuarto argumento. Pasar `null` obligaría a `telemetry?.captureException(...)` en
@@ -61,7 +64,7 @@ function envolver(surface, configFn, handler) {
61
64
  const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
62
65
  ? queueMaxRetriesCrudo
63
66
  : undefined;
64
- cliente.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
67
+ cliente.captureException(error, opcionesDelHandler(nombre, surface, primero, queueMaxRetries));
65
68
  // Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
66
69
  // decidir el 500 o el reintento del batch.
67
70
  throw error;
@@ -80,7 +83,7 @@ export function withTelemetry(configFn, handlers) {
80
83
  const handler = handlers[nombre];
81
84
  if (handler === undefined)
82
85
  continue;
83
- salida[nombre] = envolver(SUPERFICIE_POR_HANDLER[nombre], configFn, handler);
86
+ salida[nombre] = envolver(nombre, SUPERFICIE_POR_HANDLER[nombre], configFn, handler);
84
87
  }
85
88
  return salida;
86
89
  }
@@ -1 +1 @@
1
- {"version":3,"file":"with-telemetry.js","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"with-telemetry.js","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,35 @@
1
+ # Empezar
2
+
3
+ Lo transversal a cualquier puerta del paquete: instalar, la API key, el `ctx`, y qué puerta usar.
4
+
5
+ ## Instalar
6
+
7
+ ```bash
8
+ npm i @laburen/delta-sdk
9
+ ```
10
+
11
+ ## La API key va como secret
12
+
13
+ Necesitás una API key en el env del worker, como **secret** y nunca como `var`:
14
+
15
+ ```bash
16
+ wrangler secret put LABUREN_TELEMETRY_KEY
17
+ ```
18
+
19
+ Una `var` queda en texto plano en el repo y en el dashboard, y además es fácil que quede
20
+ desactualizada sin que nadie note el problema en producción.
21
+
22
+ ## El `ctx`: el original del handler, nunca una copia
23
+
24
+ Pasale a la puerta el `ctx` original del handler (`ExecutionContext` o `DurableObjectState`), no una
25
+ copia hecha con spread o `Object.create` — un patrón habitual cuando se inyecta `props` en un
26
+ `McpAgent`. Si ves el aviso de que el `ctx` tiene `waitUntil` pero no es invocable, ver
27
+ [docs/troubleshooting.md](./troubleshooting.md#el-ctx-tiene-waituntil-pero-no-es-invocable) para el
28
+ texto completo y el arreglo.
29
+
30
+ ## Qué puerta usar
31
+
32
+ - **¿Querés mandar los errores y eventos de tu worker a la ingesta de telemetría?** Usá
33
+ `@laburen/delta-sdk/telemetry` — el quickstart está en el [README](../README.md).
34
+ - La raíz del paquete (`@laburen/delta-sdk`) no tiene runtime: son los tipos compartidos entre
35
+ puertas (`Envelope`, `Notify`, `Severity`, `Surface`, `TelemetryEvent`).
@@ -100,11 +100,52 @@ vos a mano por `CaptureOptions.retry`, con el dato real:
100
100
  grande, el intento que sí agota los reintentos puede quedar **sin alertar como definitivo**. Ninguno
101
101
  de los dos sirve — omitir es lo correcto salvo que tengas el dato real.
102
102
  - En `workflow`, los números viven en el `ctx` del step (`ctx.attempt`, `ctx.config.retries.limit`),
103
- que `createTelemetry(config)` **no recibe**: si los necesitás, pasalos leyéndolos del step.
103
+ que `createTelemetry(config)` **no recibe**: si los necesitás, pasalos leyéndolos del step — cómo,
104
+ en la subsección de abajo.
104
105
 
105
106
  **Regla general: si el SDK no puede saber un dato con certeza, lo omite en vez de inventarlo.** Un
106
107
  valor inventado puede silenciar una alerta real.
107
108
 
109
+ ### `workflow`: cómo leer los números del step, y por qué acá NO se suma 1
110
+
111
+ El callback de `step.do` recibe el contexto del step **como parámetro**; no está en `this`:
112
+
113
+ ```ts
114
+ await step.do("mi-step", { retries: { limit: 3, delay: "10 seconds" } }, async (ctx) => {
115
+ try {
116
+ return await hacerAlgo();
117
+ } catch (error) {
118
+ telemetry.captureException(error, {
119
+ workUnit: ctx.step.name,
120
+ retry: { attempt: ctx.attempt, limit: ctx.config.retries?.limit },
121
+ });
122
+ throw error;
123
+ }
124
+ });
125
+ ```
126
+
127
+ Ese `ctx` trae la config **ya resuelta** por el runtime, así que no hay que hardcodear nada ni
128
+ duplicar los números que pusiste en el `step.do`:
129
+
130
+ ```json
131
+ { "step": { "name": "mi-step", "count": 1 }, "attempt": 1,
132
+ "config": { "retries": { "limit": 5, "backoff": "exponential", "delay": 10000 },
133
+ "timeout": "10 minutes" } }
134
+ ```
135
+
136
+ **Los dos valores van tal cual, sin sumarle nada.** En `workflow` el `limit` de la config **es el
137
+ total de intentos**: con `limit: 3` corren los intentos 1, 2 y 3, y `attempt` arranca en 1. Es lo
138
+ contrario que en `queue`, donde el número de la config son los reintentos **después** del primero y
139
+ hay que sumarle 1 (sección 4). Sumar 1 acá haría que el intento final **nunca** quede marcado como
140
+ definitivo.
141
+
142
+ **Y el borde que conviene conocer:** si un step **se cuelga** y el runtime lo cancela (*"the Workers
143
+ runtime canceled this request because it detected that your Worker's code had hung"*), ese intento se
144
+ reintenta **por encima** del `limit` configurado. Ahí el evento del intento que iguala al `limit` va a
145
+ decir `is_final_attempt: true` aunque todavía venga otro. Si tus steps pueden colgarse y no querés
146
+ ese riesgo, mandá `attempt` y **omití** `limit`: sin `limit` el SDK no calcula `is_final_attempt`, la
147
+ ingesta alerta en todos los intentos, y nunca declara definitivo algo que no lo es.
148
+
108
149
  ## 6. Reintentos propios: las dos palancas
109
150
 
110
151
  Si el worker reintenta **por su cuenta** —en cualquier superficie, no solo `alarm`— el SDK no puede
@@ -172,7 +213,7 @@ Bajar todo a `"warning"` acá silenciaría también la rendición final, que es
172
213
  hacen falta las dos palancas: `severity: "warning"` en los intentos intermedios y un
173
214
  `captureEvent(..., { severity: "error" })` explícito en la rendición. Es `captureEvent` y no
174
215
  `captureException` porque en ese punto **no hay ningún objeto `Error`** — es el estado D de
175
- [telemetria.md](./telemetria.md#5-los-cuatro-estados-del-código-existente).
216
+ [docs/telemetry/guia.md](./telemetry/guia.md#5-los-cuatro-estados-del-código-existente).
176
217
 
177
218
  ## 7. El batch de `queue` con `withTelemetry`
178
219
 
@@ -1,9 +1,10 @@
1
1
  # La puerta `/telemetry`, guía larga
2
2
 
3
3
  Esta es la referencia completa de `@laburen/delta-sdk/telemetry`: la config campo por campo, las
4
- `CaptureOptions`, el scrubbing y el `beforeSend`. Para los ejemplos copiables y rápidos, empezá por
5
- el [README](../README.md). Para qué cambia según dónde corre tu worker, ver
6
- [superficies.md](./superficies.md). Para el contrato exacto que viaja por la red, ver
4
+ `CaptureOptions`, el scrubbing y el `beforeSend`. Para instalar el paquete y lo transversal a
5
+ cualquier puerta (API key, `ctx`), ver [docs/empezar.md](../empezar.md). Para los ejemplos copiables
6
+ y rápidos, empezá por el [README](../../README.md). Para qué cambia según dónde corre tu worker, ver
7
+ [docs/superficies.md](../superficies.md). Para el contrato exacto que viaja por la red, ver
7
8
  [que-se-manda.md](./que-se-manda.md).
8
9
 
9
10
  ## 1. Las tres formas, y para qué sirve cada una
@@ -64,10 +65,56 @@ sirve acá:
64
65
  Es la misma razón por la que las tools que **sí** atrapan su propio error necesitan
65
66
  `captureException` a mano: ese error no escapa a ningún lado, así que ningún wrapper puede verlo.
66
67
 
68
+ ### Un helper compartido llamado desde varias superficies
69
+
70
+ En un repo con capas compartidas (`services/`, un cliente HTTP, un helper de negocio), es habitual
71
+ que la misma función se llame desde entrypoints distintos: un `fetch`, una `queue`, el `alarm()` de
72
+ un Durable Object. Si el cliente de telemetría se crea **adentro** de ese helper, su `surface` queda
73
+ fija en lo que fuera cierto en el momento en que se creó — y los eventos que en realidad vienen de
74
+ otro entrypoint llegan con la superficie equivocada. `CaptureOptions` no deja pisar `surface` por
75
+ evento, y es a propósito: la superficie es del contexto de ejecución donde corre el código, no una
76
+ propiedad de un evento individual.
77
+
78
+ **El patrón correcto: crear el cliente en el borde de la superficie, y pasarlo hacia abajo como
79
+ parámetro.** El borde es el lugar que sabe en qué superficie está corriendo —el handler, el `init()`
80
+ del Durable Object, el step de un Workflow— y ahí es donde se llama a `createTelemetry`. El helper
81
+ compartido **no** llama a `createTelemetry` por su cuenta: recibe el cliente ya armado y lo usa.
82
+
83
+ ```ts
84
+ // El helper NO crea el cliente: lo recibe, con un default inerte para no romper a quien lo
85
+ // llame sin pasarlo.
86
+ async function sincronizarPedido(
87
+ pedido: Pedido,
88
+ telemetry: Pick<TelemetryClient, "captureException"> = { captureException() {} },
89
+ ): Promise<void> {
90
+ try {
91
+ await actualizarEnZoho(pedido);
92
+ } catch (error) {
93
+ telemetry.captureException(error, { workUnit: "sincronizar-pedido" });
94
+ throw error;
95
+ }
96
+ }
97
+
98
+ // En el borde de cada superficie, el cliente se arma ahí y se pasa hacia abajo.
99
+ export default withTelemetry(configFn, {
100
+ async fetch(req, env, ctx, telemetry) {
101
+ return sincronizarPedido(await leerPedido(req), telemetry);
102
+ },
103
+ async queue(batch, env, ctx, telemetry) {
104
+ for (const mensaje of batch.messages) await sincronizarPedido(mensaje.body, telemetry);
105
+ },
106
+ });
107
+ ```
108
+
109
+ Con esto, el mismo helper reporta `surface: "worker"` cuando lo llama el `fetch` y `surface:
110
+ "queue"` cuando lo llama la `queue`, porque en cada caso el cliente que recibe se armó en ESE
111
+ borde. El cuarto argumento de `withTelemetry` ya es exactamente ese cliente armado en el borde: no
112
+ hace falta llamar a `createTelemetry` de nuevo dentro del helper, alcanza con pasarlo hacia abajo.
113
+
67
114
  ## 2. La config, campo por campo
68
115
 
69
116
  Esta es la config que recibe `createTelemetry`. `withTelemetry` recibe la misma forma **menos**
70
- `surface` y `ctx` (los pone el wrapper — ver [superficies.md](./superficies.md#8-surface-es-obligatorio-en-createtelemetry-y-no-se-escribe-con-withtelemetry)).
117
+ `surface` y `ctx` (los pone el wrapper — ver [docs/superficies.md](../superficies.md#8-surface-es-obligatorio-en-createtelemetry-y-no-se-escribe-con-withtelemetry)).
71
118
 
72
119
  | Campo | Tipo | ¿Obligatorio? | Notas |
73
120
  |---|---|---|---|
@@ -280,7 +327,7 @@ descartarlo**. Un `null` cuenta como un drop con razón `before_send` en el sobr
280
327
  reemplaza.
281
328
  - **`context.work_unit` no se scrubbea.** Es el nombre de una tool o de un paso de código —no un dato
282
329
  de usuario—, así que no metas ahí nada sensible. Ver también
283
- [troubleshooting.md](./troubleshooting.md).
330
+ [troubleshooting.md](./troubleshooting.md#dos-límites-honestos-del-scrubbing).
284
331
 
285
332
  ## 9. `beforeSend`
286
333
 
@@ -87,6 +87,17 @@ individual — es el número que decide si hace falta poner una cola de Cloudfla
87
87
  ingesta, en vez de discutirlo por intuición: si `incompletos` es consistentemente ~0, el POST directo
88
88
  alcanza; si no, hay pérdida real que una cola resolvería.
89
89
 
90
+ **El límite honesto de `fallados`: solo cuenta el error del lado del cliente, no si la ingesta está
91
+ recibiendo.** `fallados` sube **únicamente** cuando el `fetch` mismo lanza — red o DNS a nivel del
92
+ cliente. En el runtime de Cloudflare, un `fetch` a un host que no resuelve o que está caído **suele
93
+ resolver con un status de error** (por ejemplo `530`) en vez de rechazar la promesa, y esa
94
+ resolución cuenta como `completado`, nunca como `fallado`. Por eso **un `fallados: 0` no significa
95
+ que la red estuvo bien**: si la ingesta estuviera caída o inalcanzable, esos envíos se contarían
96
+ igual como `completados`, y ni `fallados` ni `incompletos` mostrarían nada distinto. El aviso de un
97
+ status `4xx`/`5xx` solo aparece con `debug: true` (sección 6). **Para saber si la ingesta está
98
+ recibiendo, la señal es la ingesta misma —no el `drops` del cliente—**, que solo puede ver lo que
99
+ pasó de su propio lado del `fetch`.
100
+
90
101
  ## 5. Los límites, y quién los aplica
91
102
 
92
103
  | Límite | Valor | Quién lo aplica |
@@ -114,7 +125,7 @@ menos detalle.
114
125
  | `200` | guardado (con `{accepted, duplicates, alerted, throttled}`) | nada |
115
126
  | `400` | payload inválido, o más de 100 eventos por sobre | **no reintenta.** Con `debug: true`, un `console.warn` |
116
127
  | `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` |
128
+ | `413` | cuerpo > 512 KB | **no reintenta.** No debería pasar si el SDK recorta bien — ver `docs/telemetry/troubleshooting.md` |
118
129
  | `503` | falló D1, o una excepción no manejada en la ingesta | **no reintenta.** Con `debug: true`, un `console.warn` |
119
130
 
120
131
  **El SDK no reintenta en ninguno de estos casos.** Cualquier respuesta —éxito o error— cuenta como
@@ -0,0 +1,48 @@
1
+ # Troubleshooting — `/telemetry`
2
+
3
+ Síntomas **propios de esta puerta**. Si tu problema es de config, del `apiKey`, del `ctx`, o de
4
+ alguno de los otros síntomas que valen para cualquier puerta del paquete, ver
5
+ [docs/troubleshooting.md](../troubleshooting.md).
6
+
7
+ ## "No llega nada" y tu `catch` devuelve un valor
8
+
9
+ Si ya revisaste los síntomas compartidos (config inválida, el aviso del `ctx`, el `apiKey`) en
10
+ [docs/troubleshooting.md](../troubleshooting.md#no-llega-nada) y seguís sin ver nada, puede ser
11
+ esto: **¿el `catch` de donde esperás que salga el evento hace `return` en vez de dejar que el error
12
+ escape?** Los wrappers (`withTool`, `withTelemetry`) solo ven lo que **escapa** de la función que
13
+ envuelven. Un `catch` que loguea y devuelve un valor —o un `.catch(() => {})`— no reporta nada, y no
14
+ es un bug: es el límite documentado en [guia.md](./guia.md). La solución es sumar
15
+ `captureException`/`captureEvent` **adentro** de ese `catch`.
16
+
17
+ ## `413`
18
+
19
+ Cuerpo de la request > 512 KB. Esto **no debería pasar en el uso normal**: el orden real del
20
+ pipeline es `scrubEvento` → `aplicarBeforeSend` → `armarSobre` → `serializarAcotado` — **el recorte
21
+ corre DESPUÉS de `beforeSend`, no antes**. Un `beforeSend` que agranda el evento (por ejemplo,
22
+ concatenando datos extra en `attributes` o en `message`) **también pasa por el recorte**: esa no es
23
+ una causa posible del `413`.
24
+
25
+ La única causa viva es esta:
26
+
27
+ **El exceso de tamaño no está en ninguno de los tres campos que el SDK sabe recortar.** El recorte
28
+ por tamaño achica, en este orden, el `stacktrace` (a 1 KB), después lo borra del todo, después vacía
29
+ `attributes`, y por último recorta el `message` a 256 caracteres — y se detiene ahí, sin llegar nunca
30
+ a descartar el evento. Si lo que hace enorme al sobre es **otro** campo — un `fingerprint` con
31
+ muchas entradas larguísimas, o un `work_unit`/`trace_id`/`conversation_id` gigantesco puesto a mano
32
+ por `CaptureOptions` — el recorte **no lo toca**, el sobre sale del mismo tamaño, y la ingesta lo
33
+ rechaza con `413`. Es un límite conocido del recorte actual: revisá el tamaño de lo que pasás en
34
+ `fingerprint` y en los identificadores de `context` si ves un `413`.
35
+
36
+ ## Dos límites honestos del scrubbing
37
+
38
+ **El scrubbing es una red, no una garantía.** Redacta por *substring* sobre nombres de clave y sobre
39
+ texto libre; un secreto guardado en un campo llamado, por ejemplo, `config` (que no contiene ningún
40
+ término de la denylist) **no se detecta**. La defensa real sigue siendo no meter secretos en el
41
+ mensaje de error — el scrubbing ataja descuidos, no los reemplaza. Y puede tener **falsos
42
+ positivos**: un mensaje como `"el token expiró"` puede quedar parcialmente redactado aunque no
43
+ llevara ningún secreto. Se calibra con datos reales de producción, no en el vacío; ver
44
+ [guia.md](./guia.md) para el detalle completo de las reglas.
45
+
46
+ **`context.work_unit` no se scrubbea.** Es el nombre de una tool o de un paso de un workflow —no un
47
+ dato de usuario—, así que no metas ahí nada sensible: una tool llamada, por ejemplo, `refreshToken`
48
+ aparece tal cual en el evento.
@@ -1,5 +1,9 @@
1
1
  # Troubleshooting
2
2
 
3
+ Síntomas **compartidos**: valen para cualquier puerta del paquete. Si tu problema es propio de
4
+ `/telemetry` (el `413`, los límites del scrubbing, o la semántica de captura de un `catch` que
5
+ devuelve un valor), ver [docs/telemetry/troubleshooting.md](./telemetry/troubleshooting.md).
6
+
3
7
  Una sección por síntoma. Si tu problema no está acá, el TypeScript real está en
4
8
  `node_modules/@laburen/delta-sdk/src/`, y se puede leer directamente.
5
9
 
@@ -13,19 +17,16 @@ Revisá en este orden:
13
17
  `agentId`, `apiKey`, `surface`, `notify`) — normalmente porque una variable del `env` no está
14
18
  seteada como se esperaba. Esto incluye un canal de `notify` declarado (`enabled: true`) pero con
15
19
  el `channel` o el `to` vacío o mal formado: no alcanza con que el otro canal esté bien. Revisá
16
- `docs/telemetria.md` para la lista completa.
20
+ `docs/telemetry/guia.md` para la lista completa.
17
21
  2. **¿Aparece el aviso del `ctx` no invocable?** Si ves *"El `ctx` recibido tiene `waitUntil` pero
18
22
  no es invocable"*, le estás pasando al SDK una **copia** del `ExecutionContext`/`DurableObjectState`
19
23
  en vez del original. Ver la sección dedicada más abajo.
20
- 3. **¿El `catch` de donde esperás que salga el evento hace `return` en vez de dejar que el error
21
- escape?** Los wrappers (`withTool`, `withTelemetry`) solo ven lo que **escapa** de la función que
22
- envuelven. Un `catch` que loguea y devuelve un valor —o un `.catch(() => {})`— no reporta nada, y
23
- no es un bug: es el límite documentado en `docs/telemetria.md`. La solución es sumar
24
- `captureException`/`captureEvent` **adentro** de ese `catch`.
25
- 4. **¿El `apiKey` es el secret correcto?** Un `401` de la ingesta sale **siempre** por
24
+ 3. **¿El `apiKey` es el secret correcto?** Un `401` de la ingesta sale **siempre** por
26
25
  `console.error`, con o sin `debug` activado, porque es config rota y tiene que verse. Si no ves
27
26
  ese `console.error` en `wrangler tail`, la clave está llegando bien y el problema es otro de los
28
- tres de arriba.
27
+ dos de arriba — o, si estás en la puerta `/telemetry`, puede ser la semántica de captura: un
28
+ `catch` que loguea y devuelve un valor en vez de dejar que el error escape. Ver
29
+ [docs/telemetry/troubleshooting.md](./telemetry/troubleshooting.md#no-llega-nada-y-tu-catch-devuelve-un-valor).
29
30
 
30
31
  ## `error 1042`
31
32
 
@@ -47,32 +48,14 @@ Revisá que el secret esté cargado con `wrangler secret put LABUREN_TELEMETRY_K
47
48
  uses) y **no** como una `var` del `wrangler.jsonc` — una `var` queda en texto plano en el repo y en
48
49
  el dashboard, y además es fácil que quede desactualizada sin que nadie note el 401 en producción.
49
50
 
50
- ## `413`
51
-
52
- Cuerpo de la request > 512 KB. Esto **no debería pasar en el uso normal**: el orden real del
53
- pipeline es `scrubEvento` → `aplicarBeforeSend` → `armarSobre` → `serializarAcotado` — **el recorte
54
- corre DESPUÉS de `beforeSend`, no antes**. Un `beforeSend` que agranda el evento (por ejemplo,
55
- concatenando datos extra en `attributes` o en `message`) **también pasa por el recorte**: esa no es
56
- una causa posible del `413`.
57
-
58
- La única causa viva es esta:
59
-
60
- **El exceso de tamaño no está en ninguno de los tres campos que el SDK sabe recortar.** El recorte
61
- por tamaño achica, en este orden, el `stacktrace` (a 1 KB), después lo borra del todo, después vacía
62
- `attributes`, y por último recorta el `message` a 256 caracteres — y se detiene ahí, sin llegar nunca
63
- a descartar el evento. Si lo que hace enorme al sobre es **otro** campo — un `fingerprint` con
64
- muchas entradas larguísimas, o un `work_unit`/`trace_id`/`conversation_id` gigantesco puesto a mano
65
- por `CaptureOptions` — el recorte **no lo toca**, el sobre sale del mismo tamaño, y la ingesta lo
66
- rechaza con `413`. Es un límite conocido del recorte actual: revisá el tamaño de lo que pasás en
67
- `fingerprint` y en los identificadores de `context` si ves un `413`.
68
-
69
51
  ## "El worker no deploya"
70
52
 
71
53
  *"Disallowed operation called within global scope."* El SDK está diseñado para no generar ids ni
72
54
  hacer ningún I/O al importarse, así que el culpable de este error casi siempre es código del propio
73
- worker: **`createTelemetry` no puede llamarse a nivel de módulo.** Tiene que ir dentro de `init()`
74
- (en un Durable Object) o dentro del handler correspondiente (en un worker plano). Y ojo:
75
- **`wrangler dev` local no detecta este error** — solo aparece recién al hacer el deploy real.
55
+ worker: **la función que arma el cliente de una puerta (`createTelemetry` en `/telemetry`) no puede
56
+ llamarse a nivel de módulo.** Tiene que ir dentro de `init()` (en un Durable Object) o dentro del
57
+ handler correspondiente (en un worker plano). Y ojo: **`wrangler dev` local no detecta este error**
58
+ — solo aparece recién al hacer el deploy real.
76
59
 
77
60
  ## "El `ctx` tiene `waitUntil` pero no es invocable"
78
61
 
@@ -97,19 +80,3 @@ invocarlo el motor lo rechaza (es el equivalente de un `TypeError: Illegal invoc
97
80
  copia — no hace falta elegir entre uno y el otro. **El framework de MCP se queda con la copia** (la
98
81
  necesita para `props`) **y el SDK recibe el original**: son dos consumidores distintos del `ctx`, y
99
82
  no compiten por él.
100
-
101
- ---
102
-
103
- ## Dos límites honestos
104
-
105
- **El scrubbing es una red, no una garantía.** Redacta por *substring* sobre nombres de clave y sobre
106
- texto libre; un secreto guardado en un campo llamado, por ejemplo, `config` (que no contiene ningún
107
- término de la denylist) **no se detecta**. La defensa real sigue siendo no meter secretos en el
108
- mensaje de error — el scrubbing ataja descuidos, no los reemplaza. Y puede tener **falsos
109
- positivos**: un mensaje como `"el token expiró"` puede quedar parcialmente redactado aunque no
110
- llevara ningún secreto. Se calibra con datos reales de producción, no en el vacío; ver
111
- `docs/telemetria.md` para el detalle completo de las reglas.
112
-
113
- **`context.work_unit` no se scrubbea.** Es el nombre de una tool o de un paso de un workflow —no un
114
- dato de usuario—, así que no metas ahí nada sensible: una tool llamada, por ejemplo, `refreshToken`
115
- aparece tal cual en el evento.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@laburen/delta-sdk",
3
- "version": "1.1.0",
4
- "description": "Cliente de telemetría para los workers de Laburen en Cloudflare",
3
+ "version": "1.3.0",
4
+ "description": "Instrumentación para los workers de Laburen en Cloudflare, sin dependencias de runtime. Puerta /telemetry: errores y eventos a la ingesta",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "license": "MIT",
@@ -5,7 +5,7 @@ export const INGEST_URL = "https://telemetry.laburen.com/events";
5
5
  export const SDK_NAME = "@laburen/delta-sdk";
6
6
 
7
7
  /** Tiene que coincidir con `version` del package.json; lo verifica `npm run version:check`. */
8
- export const SDK_VERSION = "1.1.0";
8
+ export const SDK_VERSION = "1.3.0";
9
9
 
10
10
  /** Los mismos topes que aplica la ingesta. El cliente los aplica para no perder el sobre entero;
11
11
  * la ingesta, para no confiar en el cliente. */
package/src/core/sobre.ts CHANGED
@@ -223,7 +223,7 @@ export function serializarAcotado(sobre: Envelope): { body: string; recortado: b
223
223
 
224
224
  // No cambia la política —no se descarta el evento, no se agregan pasos—, solo deja de ser
225
225
  // mudo: el exceso vive en un campo que ningún paso toca (`fingerprint`, un identificador
226
- // gigantesco), y la ingesta lo va a rechazar con 413 (docs/troubleshooting.md).
226
+ // gigantesco), y la ingesta lo va a rechazar con 413 (docs/telemetry/troubleshooting.md).
227
227
  const bytesFinales = bytesDe(body);
228
228
  if (bytesFinales > LIMITES.bodyBytes) {
229
229
  console.error(
@@ -57,17 +57,21 @@ type SoloLosPrimerosTres<F> = F extends (...args: infer Args) => infer R
57
57
 
58
58
  type HandlersEnvueltos<H extends Handlers> = { [K in keyof H]: SoloLosPrimerosTres<H[K]> };
59
59
 
60
- /** Los números del reintento que el SDK puede leer del runtime. En `queue` salen del batch; en
61
- * las otras dos superficies los pone el default de la superficie. */
60
+ /** Las opciones de la captura automática: SIEMPRE lleva `workUnit` con el nombre del handler
61
+ * (`"fetch"`, `"queue"` o `"scheduled"`) — es el mismo rol que cumple `withTool(nombre)`, y dice
62
+ * qué entrypoint falló, algo que la superficie (que ya viaja en su propio campo del sobre) no
63
+ * dice por sí sola. Además, en `queue`, suma los números del reintento que el SDK puede leer del
64
+ * batch; en las otras dos superficies los pone el default de la superficie. */
62
65
  function opcionesDelHandler(
66
+ nombre: keyof Handlers,
63
67
  surface: Surface,
64
68
  primero: unknown,
65
69
  queueMaxRetries: number | undefined,
66
70
  ): CaptureOptions {
67
- if (surface !== "queue") return {};
71
+ if (surface !== "queue") return { workUnit: nombre };
68
72
 
69
73
  const mensajes = (primero as { messages?: readonly MensajeCola[] } | null)?.messages ?? [];
70
- if (mensajes.length === 0) return {};
74
+ if (mensajes.length === 0) return { workUnit: nombre };
71
75
 
72
76
  // Un batch se reintenta ENTERO: el máximo es el intento que puede ser el final. Con el
73
77
  // mínimo, la alerta terminal podría no dispararse nunca.
@@ -80,11 +84,12 @@ function opcionesDelHandler(
80
84
  // max_retries son los reintentos DESPUÉS de la primera entrega: limit = max_retries + 1. Si
81
85
  // no está, se omite en vez de adivinar.
82
86
  return queueMaxRetries === undefined
83
- ? { retry: { attempt, workUnitId } }
84
- : { retry: { attempt, limit: queueMaxRetries + 1, workUnitId } };
87
+ ? { workUnit: nombre, retry: { attempt, workUnitId } }
88
+ : { workUnit: nombre, retry: { attempt, limit: queueMaxRetries + 1, workUnitId } };
85
89
  }
86
90
 
87
91
  function envolver<Env>(
92
+ nombre: keyof Handlers,
88
93
  surface: Surface,
89
94
  configFn: (env: Env) => HandlerTelemetryConfig,
90
95
  handler: HandlerInterno,
@@ -124,7 +129,10 @@ function envolver<Env>(
124
129
  const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
125
130
  ? queueMaxRetriesCrudo
126
131
  : undefined;
127
- cliente.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
132
+ cliente.captureException(
133
+ error,
134
+ opcionesDelHandler(nombre, surface, primero, queueMaxRetries),
135
+ );
128
136
  // Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
129
137
  // decidir el 500 o el reintento del batch.
130
138
  throw error;
@@ -148,6 +156,7 @@ export function withTelemetry<Env, H extends Handlers>(
148
156
  const handler = handlers[nombre];
149
157
  if (handler === undefined) continue;
150
158
  salida[nombre] = envolver(
159
+ nombre,
151
160
  SUPERFICIE_POR_HANDLER[nombre],
152
161
  configFn,
153
162
  handler as unknown as HandlerInterno,