@laburen/delta-sdk 1.0.1 → 1.1.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,27 @@ 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.0] — 2026-08-04
8
+
9
+ `withTelemetry` ahora le pasa el cliente de telemetría al handler. Es aditivo: no rompe ningún
10
+ handler existente.
11
+
12
+ ### Agregado
13
+
14
+ - `withTelemetry` invoca el handler con el cliente como **cuarto argumento**:
15
+ `(primero, env, ctx, telemetry)`. Un handler que declara solo tres parámetros lo ignora y sigue
16
+ funcionando igual. Ese cuarto argumento **nunca es `null` ni `undefined`**: si `configFn` lanzó y
17
+ no se pudo armar el cliente real, llega el mismo cliente inerte que devuelve `createTelemetry`
18
+ con una config inválida — descarta todo, no lanza, y su `withTool` igual corre la tool y
19
+ re-lanza.
20
+
21
+ ### Hay que hacer algo
22
+
23
+ Nada, es opcional. Pero si tu handler ya suma `captureException`/`captureEvent` a mano dentro de
24
+ un `catch` propio, podés declarar el cuarto parámetro y borrar el `createTelemetry` duplicado: el
25
+ cliente que te pasa `withTelemetry` es el mismo que usa el wrapper para su propia captura. Ver
26
+ `docs/telemetria.md`, sección 1.
27
+
7
28
  ## [1.0.1] — 2026-08-04
8
29
 
9
30
  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.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.0.1";
6
+ export const SDK_VERSION = "1.1.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 = {
@@ -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":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAShG,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;+FAG+F;AAC/F,MAAM,UAAU,aAAa;IAC5B,OAAO;QACN,gBAAgB,KAAI,CAAC;QACrB,YAAY,KAAI,CAAC;QACjB,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;KACjC,CAAC;AACH,CAAC;AAED;;;kGAGkG;AAClG,SAAS,eAAe,CAAC,QAA4B,EAAE,cAAsB;IAC5E,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC;IAClD,IAAI,YAAY,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC5C,OAAO,CAAC,KAAK,CACZ,mIAAmI,CACnI,CAAC;IACF,OAAO,cAAc,CAAC;AACvB,CAAC;AAED;;;;oFAIoF;AACpF,MAAM,UAAU,eAAe,CAAC,MAAuB;IACtD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,yFAAyF;IACzF,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,IAAI,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,iGAAiG;IACjG,8FAA8F;IAC9F,+FAA+F;IAC/F,kGAAkG;IAClG,kGAAkG;IAClG,+CAA+C;IAC/C,IAAI,SAAqC,CAAC;IAC1C,IAAI,CAAC;QACJ,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACZ,0EAA0E,EAC1E,KAAK,CACL,CAAC;QACF,OAAO,aAAa,EAAE,CAAC;IACxB,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,CACZ,uFAAuF,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpH,CAAC;QACF,OAAO,aAAa,EAAE,CAAC;IACxB,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC;IAC7B,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAEjD,MAAM,QAAQ,GAAG,CAChB,IAAuB,EACvB,OAA2B,EAC3B,SAAkD,EAClD,eAAyB,EACzB,QAAwB,EACjB,EAAE;QACT,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,WAAW,CAAC;gBAC1B,IAAI;gBACJ,OAAO;gBACP,SAAS;gBACT,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,eAAe;gBACf,QAAQ;aACR,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YAC9C,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;YACxD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACpB,8EAA8E;gBAC9E,uBAAuB;gBACvB,gBAAgB,EAAE,CAAC;gBACnB,OAAO;YACR,CAAC;YAED,MAAM,KAAK,GAAG,UAAU,CAAC;gBACxB,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,2EAA2E;gBAC3E,uEAAuE;gBACvE,sEAAsE;gBACtE,cAAc,EAAE,QAAQ,CAAC,cAAc,IAAI,GAAG,CAAC,cAAc;gBAC7D,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC;aACpD,CAAC,CAAC;YACH,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;YAE1C,MAAM,CAAC;gBACN,IAAI;gBACJ,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,GAAG,EAAE,GAAG,CAAC,SAAS;gBAClB,GAAG;gBACH,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,aAAa;aACb,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,oFAAoF;YACpF,uEAAuE;YACvE,sFAAsF;YACtF,mDAAmD;YACnD,aAAa,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,KAAK,CAAC,CAAC;QACnE,CAAC;IACF,CAAC,CAAC;IAEF;;;;;;;6FAOyF;IACzF,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAE,WAA2B,EAAE,EAAQ,EAAE;QAChF,IAAI,SAAsC,CAAC;QAC3C,IAAI,CAAC;YACJ,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,+CAA+C,EAAE,KAAK,CAAC,CAAC;YACtE,SAAS,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;QACtC,CAAC;QACD,QAAQ,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC,CAAC;IAEF;uEACmE;IACnE,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,WAA2B,EAAE,EAAQ,EAAE;QAC7E,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC5D,CAAC,CAAC;IAEF,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,EAAE,CAAC;AACtF,CAAC"}
@@ -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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"}
@@ -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.0",
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.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. */
@@ -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;