@laburen/delta-sdk 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/LICENSE +21 -0
  3. package/README.md +133 -0
  4. package/dist/core/config.d.ts +44 -0
  5. package/dist/core/config.d.ts.map +1 -0
  6. package/dist/core/config.js +163 -0
  7. package/dist/core/config.js.map +1 -0
  8. package/dist/core/constantes.d.ts +15 -0
  9. package/dist/core/constantes.d.ts.map +1 -0
  10. package/dist/core/constantes.js +15 -0
  11. package/dist/core/constantes.js.map +1 -0
  12. package/dist/core/contadores.d.ts +28 -0
  13. package/dist/core/contadores.d.ts.map +1 -0
  14. package/dist/core/contadores.js +53 -0
  15. package/dist/core/contadores.js.map +1 -0
  16. package/dist/core/scrubbing.d.ts +10 -0
  17. package/dist/core/scrubbing.d.ts.map +1 -0
  18. package/dist/core/scrubbing.js +92 -0
  19. package/dist/core/scrubbing.js.map +1 -0
  20. package/dist/core/sesion.d.ts +9 -0
  21. package/dist/core/sesion.d.ts.map +1 -0
  22. package/dist/core/sesion.js +20 -0
  23. package/dist/core/sesion.js.map +1 -0
  24. package/dist/core/sobre.d.ts +46 -0
  25. package/dist/core/sobre.d.ts.map +1 -0
  26. package/dist/core/sobre.js +200 -0
  27. package/dist/core/sobre.js.map +1 -0
  28. package/dist/core/tipos.d.ts +154 -0
  29. package/dist/core/tipos.d.ts.map +1 -0
  30. package/dist/core/tipos.js +6 -0
  31. package/dist/core/tipos.js.map +1 -0
  32. package/dist/core/transporte.d.ts +24 -0
  33. package/dist/core/transporte.d.ts.map +1 -0
  34. package/dist/core/transporte.js +70 -0
  35. package/dist/core/transporte.js.map +1 -0
  36. package/dist/index.d.ts +2 -0
  37. package/dist/index.d.ts.map +1 -0
  38. package/dist/index.js +2 -0
  39. package/dist/index.js.map +1 -0
  40. package/dist/telemetry/captura.d.ts +8 -0
  41. package/dist/telemetry/captura.d.ts.map +1 -0
  42. package/dist/telemetry/captura.js +136 -0
  43. package/dist/telemetry/captura.js.map +1 -0
  44. package/dist/telemetry/index.d.ts +5 -0
  45. package/dist/telemetry/index.d.ts.map +1 -0
  46. package/dist/telemetry/index.js +3 -0
  47. package/dist/telemetry/index.js.map +1 -0
  48. package/dist/telemetry/tipos.d.ts +2 -0
  49. package/dist/telemetry/tipos.d.ts.map +1 -0
  50. package/dist/telemetry/tipos.js +2 -0
  51. package/dist/telemetry/tipos.js.map +1 -0
  52. package/dist/telemetry/with-telemetry.d.ts +18 -0
  53. package/dist/telemetry/with-telemetry.d.ts.map +1 -0
  54. package/dist/telemetry/with-telemetry.js +81 -0
  55. package/dist/telemetry/with-telemetry.js.map +1 -0
  56. package/dist/telemetry/with-tool.d.ts +9 -0
  57. package/dist/telemetry/with-tool.d.ts.map +1 -0
  58. package/dist/telemetry/with-tool.js +20 -0
  59. package/dist/telemetry/with-tool.js.map +1 -0
  60. package/docs/que-se-manda.md +133 -0
  61. package/docs/superficies.md +239 -0
  62. package/docs/telemetria.md +258 -0
  63. package/docs/troubleshooting.md +115 -0
  64. package/package.json +61 -0
  65. package/src/core/config.ts +178 -0
  66. package/src/core/constantes.ts +17 -0
  67. package/src/core/contadores.ts +71 -0
  68. package/src/core/scrubbing.ts +104 -0
  69. package/src/core/sesion.ts +22 -0
  70. package/src/core/sobre.ts +236 -0
  71. package/src/core/tipos.ts +131 -0
  72. package/src/core/transporte.ts +93 -0
  73. package/src/index.ts +7 -0
  74. package/src/telemetry/captura.ts +161 -0
  75. package/src/telemetry/index.ts +16 -0
  76. package/src/telemetry/tipos.ts +13 -0
  77. package/src/telemetry/with-telemetry.ts +128 -0
  78. package/src/telemetry/with-tool.ts +23 -0
@@ -0,0 +1,128 @@
1
+ import { queueMaxRetriesUsable } from "../core/config.js";
2
+ import type {
3
+ CaptureOptions,
4
+ CtxLike,
5
+ HandlerTelemetryConfig,
6
+ Surface,
7
+ TelemetryClient,
8
+ } from "../core/tipos.js";
9
+ import { createTelemetry } from "./captura.js";
10
+
11
+ /** `(...args: never[]) => unknown` es el supertipo de cualquier función, sin usar `any`: deja
12
+ * pasar el handler tal como lo escribió el implementador, con SUS tipos de Cloudflare. */
13
+ type HandlerCualquiera = (...args: never[]) => unknown;
14
+
15
+ export interface Handlers {
16
+ fetch?: HandlerCualquiera;
17
+ queue?: HandlerCualquiera;
18
+ scheduled?: HandlerCualquiera;
19
+ }
20
+
21
+ /** El nombre del handler ES la superficie. No hay nada que el implementador pueda escribir mal,
22
+ * y a diferencia de los comentarios del repo, el nombre del handler no miente. */
23
+ const SUPERFICIE_POR_HANDLER = {
24
+ fetch: "worker",
25
+ queue: "queue",
26
+ scheduled: "cron",
27
+ } as const satisfies Record<keyof Handlers, Surface>;
28
+
29
+ interface MensajeCola {
30
+ id?: string;
31
+ attempts?: number;
32
+ }
33
+
34
+ type Envuelto = (primero: unknown, env: unknown, ctx: CtxLike) => Promise<unknown>;
35
+
36
+ /** Los números del reintento que el SDK puede leer del runtime. En `queue` salen del batch; en
37
+ * las otras dos superficies los pone el default de la superficie. */
38
+ function opcionesDelHandler(
39
+ surface: Surface,
40
+ primero: unknown,
41
+ queueMaxRetries: number | undefined,
42
+ ): CaptureOptions {
43
+ if (surface !== "queue") return {};
44
+
45
+ const mensajes = (primero as { messages?: readonly MensajeCola[] } | null)?.messages ?? [];
46
+ if (mensajes.length === 0) return {};
47
+
48
+ // Un batch se reintenta ENTERO: el máximo es el intento que puede ser el final. Con el
49
+ // mínimo, la alerta terminal podría no dispararse nunca.
50
+ const attempt = Math.max(...mensajes.map((mensaje) => mensaje.attempts ?? 1));
51
+ // Un batch no tiene un único mensaje del que colgar el id. Para capturar por mensaje va
52
+ // createTelemetry, y está documentado en docs/superficies.md.
53
+ const primerMensaje = mensajes.length === 1 ? mensajes[0] : undefined;
54
+ const workUnitId = primerMensaje?.id ?? null;
55
+
56
+ // max_retries son los reintentos DESPUÉS de la primera entrega: limit = max_retries + 1. Si
57
+ // no está, se omite en vez de adivinar.
58
+ return queueMaxRetries === undefined
59
+ ? { retry: { attempt, workUnitId } }
60
+ : { retry: { attempt, limit: queueMaxRetries + 1, workUnitId } };
61
+ }
62
+
63
+ function envolver<Env>(
64
+ surface: Surface,
65
+ configFn: (env: Env) => HandlerTelemetryConfig,
66
+ handler: Envuelto,
67
+ ): Envuelto {
68
+ return async (primero, env, ctx) => {
69
+ let cliente: TelemetryClient | null = null;
70
+ let cfg: HandlerTelemetryConfig | null = null;
71
+
72
+ try {
73
+ cfg = configFn(env as Env);
74
+ // `surface` y `ctx` los pone el wrapper: el tipo se los prohíbe al implementador para
75
+ // que no pueda pisarlos con un valor equivocado.
76
+ const { surface: _surface, ctx: _ctx, ...resto } = cfg;
77
+ cliente = createTelemetry({ ...resto, surface, ctx });
78
+ } catch (error) {
79
+ // Si la telemetría no arranca, el handler del cliente corre igual.
80
+ console.error(
81
+ "[delta-sdk] no se pudo inicializar la telemetría; el handler sigue igual",
82
+ error,
83
+ );
84
+ }
85
+
86
+ try {
87
+ return await handler(primero, env, ctx);
88
+ } catch (error) {
89
+ // `cfg` es la config CRUDA que devolvió `configFn`, no la `ConfigValidada` de
90
+ // `createTelemetry`: este camino no pasa por `validar`, así que hay que sanearlo acá
91
+ // también. El aviso de un valor inválido ya lo emite `createTelemetry` más arriba,
92
+ // al validar la misma config para construir `cliente`.
93
+ const queueMaxRetriesCrudo = cfg?.queueMaxRetries;
94
+ const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
95
+ ? queueMaxRetriesCrudo
96
+ : undefined;
97
+ cliente?.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
98
+ // Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
99
+ // decidir el 500 o el reintento del batch.
100
+ throw error;
101
+ }
102
+ };
103
+ }
104
+
105
+ /** Envuelve el `export default` de un worker. Recibe la config como FUNCIÓN de `env` y no como
106
+ * objeto ya armado, porque el `env` no existe a nivel de módulo y evaluar la config ahí sería
107
+ * el mismo error que genera ids en el scope global.
108
+ *
109
+ * Solo ve lo que ESCAPA del handler: un `catch` que loguea y devuelve un valor no deja escapar
110
+ * nada, y el wrapper no se entera. Envolver no reemplaza revisar los `catch` que ya existen. */
111
+ export function withTelemetry<Env, H extends Handlers>(
112
+ configFn: (env: Env) => HandlerTelemetryConfig,
113
+ handlers: H,
114
+ ): H {
115
+ const salida = { ...handlers } as H;
116
+
117
+ for (const nombre of ["fetch", "queue", "scheduled"] as const) {
118
+ const handler = handlers[nombre];
119
+ if (handler === undefined) continue;
120
+ salida[nombre] = envolver(
121
+ SUPERFICIE_POR_HANDLER[nombre],
122
+ configFn,
123
+ handler as unknown as Envuelto,
124
+ ) as H[typeof nombre];
125
+ }
126
+
127
+ return salida;
128
+ }
@@ -0,0 +1,23 @@
1
+ import type { CaptureOptions, TelemetryClient } from "../core/tipos.js";
2
+
3
+ /** Envuelve una tool de MCP. El implementador NO escribe captureException en ninguna tool: lo
4
+ * hace este wrapper, una vez, para todas las que envuelva. Ese es el aporte.
5
+ *
6
+ * Tres requisitos, no sugerencias: reenvía TODOS los argumentos porque el SDK invoca con
7
+ * `(args, extra)`; re-lanza EL MISMO objeto de error porque su mensaje es el que ve el usuario
8
+ * final; y es arrow function para no introducir un `this` propio. */
9
+ export function crearWithTool(
10
+ capturar: (error: unknown, opciones: CaptureOptions) => void,
11
+ ): TelemetryClient["withTool"] {
12
+ return <Args extends unknown[], R>(nombre: string, fn: (...args: Args) => R | Promise<R>) =>
13
+ async (...args: Args): Promise<R> => {
14
+ try {
15
+ return await fn(...args);
16
+ } catch (error) {
17
+ // El reporte vive acá y en ningún otro lado. Y solo llega si `fn` LANZA: una tool
18
+ // que atrapa su propio error y devuelve un valor no pasa por acá.
19
+ capturar(error, { workUnit: nombre });
20
+ throw error;
21
+ }
22
+ };
23
+ }