@laburen/delta-sdk 1.0.1 → 1.1.1

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,49 @@ 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.1.1] — 2026-08-04
8
+
9
+ Solo documentación. **El código no cambió**: si ya estás en `1.1.0`, actualizar es opcional.
10
+
11
+ ### Cambiado
12
+
13
+ - `docs/superficies.md` ahora explica **cómo leer los números del reintento en `surface: "workflow"`**:
14
+ que el callback de `step.do` recibe el contexto del step **como parámetro** (no está en `this`), con
15
+ la forma real del objeto, y que **los valores van tal cual, sin sumarle 1** — en `workflow` el
16
+ `limit` de la config **es el total de intentos**, al revés que en `queue`. Sumar 1 ahí haría que el
17
+ intento final nunca quede marcado como definitivo.
18
+ - Queda documentado un borde del runtime: un step que **se cuelga** y es cancelado por el runtime se
19
+ reintenta **por encima** del `limit` configurado, así que el evento del intento que iguala al `limit`
20
+ puede decir `is_final_attempt: true` con otro intento todavía por venir. Con la salida recomendada
21
+ para ese caso: mandar `attempt` y omitir `limit`.
22
+
23
+ ### Hay que hacer algo
24
+
25
+ Nada. Pero si instrumentaste un Workflow y no estabas mandando `retry` porque no encontrabas de dónde
26
+ salían los números, ahora está escrito: son `ctx.attempt` y `ctx.config.retries?.limit` del callback
27
+ del step.
28
+
29
+ ## [1.1.0] — 2026-08-04
30
+
31
+ `withTelemetry` ahora le pasa el cliente de telemetría al handler. Es aditivo: no rompe ningún
32
+ handler existente.
33
+
34
+ ### Agregado
35
+
36
+ - `withTelemetry` invoca el handler con el cliente como **cuarto argumento**:
37
+ `(primero, env, ctx, telemetry)`. Un handler que declara solo tres parámetros lo ignora y sigue
38
+ funcionando igual. Ese cuarto argumento **nunca es `null` ni `undefined`**: si `configFn` lanzó y
39
+ no se pudo armar el cliente real, llega el mismo cliente inerte que devuelve `createTelemetry`
40
+ con una config inválida — descarta todo, no lanza, y su `withTool` igual corre la tool y
41
+ re-lanza.
42
+
43
+ ### Hay que hacer algo
44
+
45
+ Nada, es opcional. Pero si tu handler ya suma `captureException`/`captureEvent` a mano dentro de
46
+ un `catch` propio, podés declarar el cuarto parámetro y borrar el `createTelemetry` duplicado: el
47
+ cliente que te pasa `withTelemetry` es el mismo que usa el wrapper para su propia captura. Ver
48
+ `docs/telemetria.md`, sección 1.
49
+
7
50
  ## [1.0.1] — 2026-08-04
8
51
 
9
52
  Solo documentación. **El código no cambió**: si ya estás en `1.0.0`, actualizar es opcional.
package/README.md CHANGED
@@ -90,15 +90,19 @@ export default withTelemetry(
90
90
  queueMaxRetries: 3, // el MISMO número del wrangler.jsonc, sin sumarle 1
91
91
  }),
92
92
  {
93
- async fetch(req, env, ctx) { /* ... */ }, // → surface "worker"
94
- async queue(batch, env, ctx) { /* ... */ }, // → surface "queue"
95
- async scheduled(ctrl, env, ctx) { /* ... */ }, // → surface "cron"
93
+ async fetch(req, env, ctx, telemetry) { /* ... */ }, // → surface "worker"
94
+ async queue(batch, env, ctx) { /* ... */ }, // → surface "queue"
95
+ async scheduled(ctrl, env, ctx) { /* ... */ }, // → surface "cron"
96
96
  },
97
97
  );
98
98
  ```
99
99
 
100
100
  La config **no lleva `surface`**: se deduce del nombre del handler, y pasarla no compila.
101
101
 
102
+ **El cuarto argumento (`telemetry`) es el mismo cliente que usa el wrapper.** Un handler que
103
+ 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).
105
+
102
106
  > **Los nombres de las env var no están estandarizados entre proyectos.** Abrí tu `env.d.ts` antes
103
107
  > de copiar los nombres: no asumas que son los mismos que en otro worker.
104
108
 
@@ -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.0.1";
6
+ export declare const SDK_VERSION = "1.1.1";
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.0.1";
6
+ export const SDK_VERSION = "1.1.1";
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 = {
@@ -1,4 +1,9 @@
1
1
  import type { TelemetryClient, TelemetryConfig } from "../core/tipos.js";
2
+ /** Descarta todo, pero `withTool` sigue corriendo la tool y re-lanzando: un cliente inerte no
3
+ * puede cambiar el comportamiento de la app. Exportado (pero no re-exportado por ninguna puerta
4
+ * del `exports` map) para que `with-telemetry.ts` lo use como el cuarto argumento del handler
5
+ * cuando `configFn` lanza: el invariante es que ese argumento nunca es `null`/`undefined`. */
6
+ export declare function clienteInerte(): TelemetryClient;
2
7
  /** El núcleo explícito, y el camino principal: los dos wrappers se construyen sobre esto y
3
8
  * ninguno puede hacer nada que esto no permita.
4
9
  *
@@ -1 +1 @@
1
- {"version":3,"file":"captura.d.ts","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAIX,eAAe,EACf,eAAe,EAEf,MAAM,kBAAkB,CAAC;AA2B1B;;;;oFAIoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAqHxE"}
1
+ {"version":3,"file":"captura.d.ts","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAIX,eAAe,EACf,eAAe,EAEf,MAAM,kBAAkB,CAAC;AAI1B;;;+FAG+F;AAC/F,wBAAgB,aAAa,IAAI,eAAe,CAM/C;AAeD;;;;oFAIoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAqHxE"}
@@ -5,8 +5,10 @@ import { armarEvento, armarSobre, extraerException, serializarAcotado } from "..
5
5
  import { AVISO_CTX_ROTO, enviar, probarCtx } from "../core/transporte.js";
6
6
  import { crearWithTool } from "./with-tool.js";
7
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() {
8
+ * puede cambiar el comportamiento de la app. Exportado (pero no re-exportado por ninguna puerta
9
+ * del `exports` map) para que `with-telemetry.ts` lo use como el cuarto argumento del handler
10
+ * cuando `configFn` lanza: el invariante es que ese argumento nunca es `null`/`undefined`. */
11
+ export function clienteInerte() {
10
12
  return {
11
13
  captureException() { },
12
14
  captureEvent() { },
@@ -1 +1 @@
1
- {"version":3,"file":"captura.js","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"captura.js","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"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"}
@@ -7,12 +7,20 @@ export interface Handlers {
7
7
  queue?: HandlerCualquiera;
8
8
  scheduled?: HandlerCualquiera;
9
9
  }
10
+ /** Recorta el tipo de un handler a sus primeros tres parámetros, preservando el resto: es lo
11
+ * único que un caller externo puede llegar a pasar. Sin esto, un handler que declara el cuarto
12
+ * parámetro (`telemetry`) haría que `withTelemetry` devolviera un tipo que exige ESE cuarto
13
+ * argumento también al invocarlo desde afuera — cuando en realidad lo agrega el wrapper. */
14
+ type SoloLosPrimerosTres<F> = F extends (...args: infer Args) => infer R ? Args extends [infer P1, infer P2, infer P3, ...unknown[]] ? (p1: P1, p2: P2, p3: P3) => R : F : F;
15
+ type HandlersEnvueltos<H extends Handlers> = {
16
+ [K in keyof H]: SoloLosPrimerosTres<H[K]>;
17
+ };
10
18
  /** Envuelve el `export default` de un worker. Recibe la config como FUNCIÓN de `env` y no como
11
19
  * objeto ya armado, porque el `env` no existe a nivel de módulo y evaluar la config ahí sería
12
20
  * el mismo error que genera ids en el scope global.
13
21
  *
14
22
  * Solo ve lo que ESCAPA del handler: un `catch` que loguea y devuelve un valor no deja escapar
15
23
  * 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;
24
+ export declare function withTelemetry<Env, H extends Handlers>(configFn: (env: Env) => HandlerTelemetryConfig, handlers: H): HandlersEnvueltos<H>;
17
25
  export {};
18
26
  //# sourceMappingURL=with-telemetry.d.ts.map
@@ -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;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"}
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,5 +1,5 @@
1
1
  import { queueMaxRetriesUsable } from "../core/config.js";
2
- import { createTelemetry } from "./captura.js";
2
+ import { clienteInerte, createTelemetry } from "./captura.js";
3
3
  /** El nombre del handler ES la superficie. No hay nada que el implementador pueda escribir mal,
4
4
  * y a diferencia de los comentarios del repo, el nombre del handler no miente. */
5
5
  const SUPERFICIE_POR_HANDLER = {
@@ -30,7 +30,10 @@ function opcionesDelHandler(surface, primero, queueMaxRetries) {
30
30
  }
31
31
  function envolver(surface, configFn, handler) {
32
32
  return async (primero, env, ctx) => {
33
- let cliente = null;
33
+ // Nunca queda en `null`: si `configFn` lanza, el handler recibe igual el cliente inerte
34
+ // como cuarto argumento. Pasar `null` obligaría a `telemetry?.captureException(...)` en
35
+ // cada consumidor, y el que se olvide del `?.` se rompería solo con un TypeError.
36
+ let cliente;
34
37
  let cfg = null;
35
38
  try {
36
39
  cfg = configFn(env);
@@ -42,9 +45,12 @@ function envolver(surface, configFn, handler) {
42
45
  catch (error) {
43
46
  // Si la telemetría no arranca, el handler del cliente corre igual.
44
47
  console.error("[delta-sdk] no se pudo inicializar la telemetría; el handler sigue igual", error);
48
+ cliente = clienteInerte();
45
49
  }
46
50
  try {
47
- return await handler(primero, env, ctx);
51
+ // El cliente como cuarto argumento: el implementador puede usarlo en su propio catch
52
+ // sin llamar a createTelemetry de nuevo ni duplicar la config.
53
+ return await handler(primero, env, ctx, cliente);
48
54
  }
49
55
  catch (error) {
50
56
  // `cfg` es la config CRUDA que devolvió `configFn`, no la `ConfigValidada` de
@@ -55,7 +61,7 @@ function envolver(surface, configFn, handler) {
55
61
  const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
56
62
  ? queueMaxRetriesCrudo
57
63
  : undefined;
58
- cliente?.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
64
+ cliente.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
59
65
  // Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
60
66
  // decidir el 500 o el reintento del batch.
61
67
  throw error;
@@ -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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"}
@@ -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
@@ -11,7 +11,7 @@ el [README](../README.md). Para qué cambia según dónde corre tu worker, ver
11
11
  | Forma | Cuándo | Qué resuelve |
12
12
  |---|---|---|
13
13
  | **`createTelemetry(config)` + `captureException`/`captureEvent`** | **cualquier situación — es el camino principal** | el núcleo explícito. Devuelve el **cliente**, y las otras dos formas se construyen sobre esto |
14
- | `withTelemetry(configFn, handlers)` | worker plano, `queue`, `cron` | envuelve el `export default`; provee `env` y `ctx`; deduce la superficie por el nombre del handler; captura lo que **escapa** del handler |
14
+ | `withTelemetry(configFn, handlers)` | worker plano, `queue`, `cron` | envuelve el `export default`; provee `env`, `ctx` y el **cliente como cuarto argumento**; deduce la superficie por el nombre del handler; captura lo que **escapa** del handler |
15
15
  | `telemetry.withTool(nombre, fn)` | tools de MCP que **hoy no atrapan su error** | envuelve una tool; captura y **re-lanza**; ahorra escribir el `try/catch` |
16
16
 
17
17
  **`createTelemetry` es el camino principal.** Los dos wrappers son atajos que se arman encima: ni
@@ -24,6 +24,30 @@ entera. En la práctica, el grueso del trabajo de instrumentar un worker existen
24
24
  con estos wrappers: es sumar `captureException`/`captureEvent` a mano dentro de los `catch` que ya
25
25
  existen. Ver la sección 5.
26
26
 
27
+ **`withTelemetry` le pasa el cliente al handler como cuarto argumento**, así que ese trabajo de
28
+ sumar `captureException`/`captureEvent` a mano **no** requiere llamar a `createTelemetry` de nuevo
29
+ ni duplicar la config: el cliente ya armado está ahí, en el cuarto parámetro. Un handler que
30
+ declara solo tres sigue andando igual — es aditivo.
31
+
32
+ ```ts
33
+ export default withTelemetry(configFn, {
34
+ async fetch(req, env, ctx, telemetry) {
35
+ try {
36
+ return await manejarRequest(req);
37
+ } catch (error) {
38
+ // el MISMO cliente que arma el wrapper, sin volver a llamar a createTelemetry
39
+ telemetry.captureException(error, { workUnit: "manejar-request" });
40
+ return new Response("Ocurrió un error", { status: 500 });
41
+ }
42
+ },
43
+ });
44
+ ```
45
+
46
+ Ese cuarto argumento **nunca es `null` ni `undefined`**: si `configFn` lanzó y no se pudo armar el
47
+ cliente real, llega el mismo cliente inerte que devuelve `createTelemetry` con una config inválida
48
+ — descarta todo, no lanza, y su `withTool` igual corre la tool y re-lanza. Así ningún consumidor
49
+ necesita escribir `telemetry?.captureException(...)`.
50
+
27
51
  ### Un MCP sobre Durable Object: qué va y qué no
28
52
 
29
53
  Un MCP hecho con `McpAgent` tiene las dos formas a la vez: un `export default { fetch }` que rutea
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@laburen/delta-sdk",
3
- "version": "1.0.1",
3
+ "version": "1.1.1",
4
4
  "description": "Cliente de telemetría para los workers de Laburen en Cloudflare",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -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.0.1";
8
+ export const SDK_VERSION = "1.1.1";
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. */
@@ -14,8 +14,10 @@ import { AVISO_CTX_ROTO, enviar, probarCtx } from "../core/transporte.js";
14
14
  import { crearWithTool } from "./with-tool.js";
15
15
 
16
16
  /** Descarta todo, pero `withTool` sigue corriendo la tool y re-lanzando: un cliente inerte no
17
- * puede cambiar el comportamiento de la app. */
18
- function clienteInerte(): TelemetryClient {
17
+ * puede cambiar el comportamiento de la app. Exportado (pero no re-exportado por ninguna puerta
18
+ * del `exports` map) para que `with-telemetry.ts` lo use como el cuarto argumento del handler
19
+ * cuando `configFn` lanza: el invariante es que ese argumento nunca es `null`/`undefined`. */
20
+ export function clienteInerte(): TelemetryClient {
19
21
  return {
20
22
  captureException() {},
21
23
  captureEvent() {},
@@ -6,7 +6,7 @@ import type {
6
6
  Surface,
7
7
  TelemetryClient,
8
8
  } from "../core/tipos.js";
9
- import { createTelemetry } from "./captura.js";
9
+ import { clienteInerte, createTelemetry } from "./captura.js";
10
10
 
11
11
  /** `(...args: never[]) => unknown` es el supertipo de cualquier función, sin usar `any`: deja
12
12
  * pasar el handler tal como lo escribió el implementador, con SUS tipos de Cloudflare. */
@@ -31,8 +31,32 @@ interface MensajeCola {
31
31
  attempts?: number;
32
32
  }
33
33
 
34
+ // El handler tal como lo escribe el implementador: el wrapper lo llama SIEMPRE con el cliente
35
+ // como cuarto argumento. Un handler que declara solo tres lo ignora y sigue andando igual.
36
+ type HandlerInterno = (
37
+ primero: unknown,
38
+ env: unknown,
39
+ ctx: CtxLike,
40
+ telemetry: TelemetryClient,
41
+ ) => Promise<unknown>;
42
+
43
+ // Lo que expone `withTelemetry`: solo los tres parámetros que el runtime (Cloudflare, o quien
44
+ // invoque el `export default`) puede llegar a pasar. El cuarto lo agrega `envolver` puertas
45
+ // adentro, nunca el caller externo, así que el tipo expuesto no puede exigirlo.
34
46
  type Envuelto = (primero: unknown, env: unknown, ctx: CtxLike) => Promise<unknown>;
35
47
 
48
+ /** Recorta el tipo de un handler a sus primeros tres parámetros, preservando el resto: es lo
49
+ * único que un caller externo puede llegar a pasar. Sin esto, un handler que declara el cuarto
50
+ * parámetro (`telemetry`) haría que `withTelemetry` devolviera un tipo que exige ESE cuarto
51
+ * argumento también al invocarlo desde afuera — cuando en realidad lo agrega el wrapper. */
52
+ type SoloLosPrimerosTres<F> = F extends (...args: infer Args) => infer R
53
+ ? Args extends [infer P1, infer P2, infer P3, ...unknown[]]
54
+ ? (p1: P1, p2: P2, p3: P3) => R
55
+ : F
56
+ : F;
57
+
58
+ type HandlersEnvueltos<H extends Handlers> = { [K in keyof H]: SoloLosPrimerosTres<H[K]> };
59
+
36
60
  /** Los números del reintento que el SDK puede leer del runtime. En `queue` salen del batch; en
37
61
  * las otras dos superficies los pone el default de la superficie. */
38
62
  function opcionesDelHandler(
@@ -63,10 +87,13 @@ function opcionesDelHandler(
63
87
  function envolver<Env>(
64
88
  surface: Surface,
65
89
  configFn: (env: Env) => HandlerTelemetryConfig,
66
- handler: Envuelto,
90
+ handler: HandlerInterno,
67
91
  ): Envuelto {
68
92
  return async (primero, env, ctx) => {
69
- let cliente: TelemetryClient | null = null;
93
+ // Nunca queda en `null`: si `configFn` lanza, el handler recibe igual el cliente inerte
94
+ // como cuarto argumento. Pasar `null` obligaría a `telemetry?.captureException(...)` en
95
+ // cada consumidor, y el que se olvide del `?.` se rompería solo con un TypeError.
96
+ let cliente: TelemetryClient;
70
97
  let cfg: HandlerTelemetryConfig | null = null;
71
98
 
72
99
  try {
@@ -81,10 +108,13 @@ function envolver<Env>(
81
108
  "[delta-sdk] no se pudo inicializar la telemetría; el handler sigue igual",
82
109
  error,
83
110
  );
111
+ cliente = clienteInerte();
84
112
  }
85
113
 
86
114
  try {
87
- return await handler(primero, env, ctx);
115
+ // El cliente como cuarto argumento: el implementador puede usarlo en su propio catch
116
+ // sin llamar a createTelemetry de nuevo ni duplicar la config.
117
+ return await handler(primero, env, ctx, cliente);
88
118
  } catch (error) {
89
119
  // `cfg` es la config CRUDA que devolvió `configFn`, no la `ConfigValidada` de
90
120
  // `createTelemetry`: este camino no pasa por `validar`, así que hay que sanearlo acá
@@ -94,7 +124,7 @@ function envolver<Env>(
94
124
  const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
95
125
  ? queueMaxRetriesCrudo
96
126
  : undefined;
97
- cliente?.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
127
+ cliente.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
98
128
  // Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
99
129
  // decidir el 500 o el reintento del batch.
100
130
  throw error;
@@ -111,8 +141,8 @@ function envolver<Env>(
111
141
  export function withTelemetry<Env, H extends Handlers>(
112
142
  configFn: (env: Env) => HandlerTelemetryConfig,
113
143
  handlers: H,
114
- ): H {
115
- const salida = { ...handlers } as H;
144
+ ): HandlersEnvueltos<H> {
145
+ const salida = { ...handlers } as unknown as HandlersEnvueltos<H>;
116
146
 
117
147
  for (const nombre of ["fetch", "queue", "scheduled"] as const) {
118
148
  const handler = handlers[nombre];
@@ -120,8 +150,8 @@ export function withTelemetry<Env, H extends Handlers>(
120
150
  salida[nombre] = envolver(
121
151
  SUPERFICIE_POR_HANDLER[nombre],
122
152
  configFn,
123
- handler as unknown as Envuelto,
124
- ) as H[typeof nombre];
153
+ handler as unknown as HandlerInterno,
154
+ ) as HandlersEnvueltos<H>[typeof nombre];
125
155
  }
126
156
 
127
157
  return salida;