@laburen/delta-sdk 1.1.0 → 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,28 @@ 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
+
7
29
  ## [1.1.0] — 2026-08-04
8
30
 
9
31
  `withTelemetry` ahora le pasa el cliente de telemetría al handler. Es aditivo: no rompe ningún
@@ -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.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.1.0";
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 = {
@@ -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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@laburen/delta-sdk",
3
- "version": "1.1.0",
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.1.0";
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. */