@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 @@
1
+ {"version":3,"file":"scrubbing.js","sourceRoot":"","sources":["../../src/core/scrubbing.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,9 @@
1
+ /** El id del isolate. Perezoso: generarlo al cargar el módulo hace fallar el deploy del worker
2
+ * del cliente, y `wrangler dev` local no lo detecta. */
3
+ export declare function session(): string;
4
+ /** Arranca en 1 y no se reinicia: la ingesta detecta los huecos comparando los seq que le
5
+ * llegan. Detecta huecos en el medio, no una cola cortada. */
6
+ export declare function nextSeq(): number;
7
+ /** Solo para los tests. No sale por ninguna puerta del `exports` map. */
8
+ export declare function reiniciarSesion(): void;
9
+ //# sourceMappingURL=sesion.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sesion.d.ts","sourceRoot":"","sources":["../../src/core/sesion.ts"],"names":[],"mappings":"AAGA;yDACyD;AACzD,wBAAgB,OAAO,IAAI,MAAM,CAGhC;AAED;+DAC+D;AAC/D,wBAAgB,OAAO,IAAI,MAAM,CAGhC;AAED,yEAAyE;AACzE,wBAAgB,eAAe,IAAI,IAAI,CAGtC"}
@@ -0,0 +1,20 @@
1
+ let _session = null;
2
+ let _seq = 0;
3
+ /** El id del isolate. Perezoso: generarlo al cargar el módulo hace fallar el deploy del worker
4
+ * del cliente, y `wrangler dev` local no lo detecta. */
5
+ export function session() {
6
+ // biome-ignore lint/suspicious/noAssignInExpressions: el `??=` perezoso es el punto del diseño.
7
+ return (_session ??= crypto.randomUUID().slice(0, 8));
8
+ }
9
+ /** Arranca en 1 y no se reinicia: la ingesta detecta los huecos comparando los seq que le
10
+ * llegan. Detecta huecos en el medio, no una cola cortada. */
11
+ export function nextSeq() {
12
+ _seq += 1;
13
+ return _seq;
14
+ }
15
+ /** Solo para los tests. No sale por ninguna puerta del `exports` map. */
16
+ export function reiniciarSesion() {
17
+ _session = null;
18
+ _seq = 0;
19
+ }
20
+ //# sourceMappingURL=sesion.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sesion.js","sourceRoot":"","sources":["../../src/core/sesion.ts"],"names":[],"mappings":"AAAA,IAAI,QAAQ,GAAkB,IAAI,CAAC;AACnC,IAAI,IAAI,GAAG,CAAC,CAAC;AAEb;yDACyD;AACzD,MAAM,UAAU,OAAO;IACtB,gGAAgG;IAChG,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;+DAC+D;AAC/D,MAAM,UAAU,OAAO;IACtB,IAAI,IAAI,CAAC,CAAC;IACV,OAAO,IAAI,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,eAAe;IAC9B,QAAQ,GAAG,IAAI,CAAC;IAChB,IAAI,GAAG,CAAC,CAAC;AACV,CAAC"}
@@ -0,0 +1,46 @@
1
+ import type { CaptureOptions, Envelope, Notify, RetryInfo, Severity, Surface, TelemetryEvent } from "./tipos.js";
2
+ /** El mismo truncado que aplica la ingesta del lado servidor. */
3
+ export declare function truncar(valor: string, max: number): string;
4
+ /** Deja las primeras 64 claves. Los valores ya son escalares por tipo, así que no hay nada que
5
+ * serializar del lado del cliente. */
6
+ export declare function acotarAttributes(attrs: Record<string, string | number | boolean> | undefined): Record<string, string | number | boolean> | undefined;
7
+ /** Semántica de excepciones de OTel: type, message y stacktrace. */
8
+ export declare function extraerException(error: unknown): TelemetryEvent["exception"];
9
+ /** Solo devuelve números donde el SDK REALMENTE los sabe. En `alarm` los maneja el repo, en
10
+ * `workflow` viven en el ctx del step y en `queue` en el mensaje: ahí se omite el bloque, porque
11
+ * un valor inventado silencia la alerta terminal. */
12
+ export declare function retryPorSuperficie(surface: Surface): TelemetryEvent["retry"] | undefined;
13
+ /** Mapea los números de camelCase (API pública) a snake_case (contrato). */
14
+ export declare function retryDesdeOpciones(info: RetryInfo): NonNullable<TelemetryEvent["retry"]>;
15
+ export interface ArgsEvento {
16
+ tipo: "error" | "event";
17
+ mensaje: string | undefined;
18
+ exception: TelemetryEvent["exception"] | undefined;
19
+ agentId: string;
20
+ surface: Surface;
21
+ severityDefault: Severity;
22
+ opciones: CaptureOptions;
23
+ }
24
+ export declare function armarEvento(args: ArgsEvento): TelemetryEvent;
25
+ export interface ArgsSobre {
26
+ evento: TelemetryEvent;
27
+ service: {
28
+ name: string;
29
+ version?: string;
30
+ environment?: string;
31
+ };
32
+ organizationId: string;
33
+ surface: Surface;
34
+ notify: Notify;
35
+ }
36
+ /** Un sobre por captura, sin batching: el caso es 1 error por invocación, y batchear exigiría un
37
+ * punto de flush, que es justo donde se pierde data. */
38
+ export declare function armarSobre(args: ArgsSobre): Envelope;
39
+ /** Recorta el sobre hasta que entre en el tope de bytes. NUNCA descarta el evento: un error con
40
+ * stacktrace enorme sigue siendo un error que hay que reportar. Muta el sobre, que es
41
+ * recién armado y de este módulo. */
42
+ export declare function serializarAcotado(sobre: Envelope): {
43
+ body: string;
44
+ recortado: boolean;
45
+ };
46
+ //# sourceMappingURL=sobre.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sobre.d.ts","sourceRoot":"","sources":["../../src/core/sobre.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,cAAc,EACd,QAAQ,EACR,MAAM,EACN,SAAS,EACT,QAAQ,EACR,OAAO,EACP,cAAc,EACd,MAAM,YAAY,CAAC;AAEpB,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAOD;uCACuC;AACvC,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,SAAS,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,SAAS,CAIvD;AAWD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,WAAW,CAAC,CAW5E;AASD;;sDAEsD;AACtD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,SAAS,CASxF;AAQD,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAaxF;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,EAAE,cAAc,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,QAAQ,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;CACzB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAmD5D;AAED,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf;AAED;yDACyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAiBpD;AAED;;sCAEsC;AACtC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAyCvF"}
@@ -0,0 +1,200 @@
1
+ import { LIMITES, SDK_NAME, SDK_VERSION } from "./constantes.js";
2
+ import { contarRecortado, drops } from "./contadores.js";
3
+ import { nextSeq, session } from "./sesion.js";
4
+ /** El mismo truncado que aplica la ingesta del lado servidor. */
5
+ export function truncar(valor, max) {
6
+ return valor.length <= max ? valor : `${valor.slice(0, max)}…[truncado]`;
7
+ }
8
+ function bytesDe(texto) {
9
+ // Se mide en bytes y no en caracteres, igual que la ingesta: un `é` ocupa 2 en UTF-8.
10
+ return new TextEncoder().encode(texto).byteLength;
11
+ }
12
+ /** Deja las primeras 64 claves. Los valores ya son escalares por tipo, así que no hay nada que
13
+ * serializar del lado del cliente. */
14
+ export function acotarAttributes(attrs) {
15
+ if (attrs === undefined)
16
+ return undefined;
17
+ const entradas = Object.entries(attrs).slice(0, LIMITES.attributeKeys);
18
+ return Object.fromEntries(entradas);
19
+ }
20
+ function textoDe(valor) {
21
+ try {
22
+ return typeof valor === "string" ? valor : (JSON.stringify(valor) ?? String(valor));
23
+ }
24
+ catch {
25
+ // Un objeto con referencias circulares no puede hacer perder el evento.
26
+ return String(valor);
27
+ }
28
+ }
29
+ /** Semántica de excepciones de OTel: type, message y stacktrace. */
30
+ export function extraerException(error) {
31
+ if (error instanceof Error) {
32
+ const salida = {
33
+ type: error.name,
34
+ message: error.message,
35
+ };
36
+ if (error.stack !== undefined)
37
+ salida.stacktrace = error.stack;
38
+ return salida;
39
+ }
40
+ // Varios repos de cliente lanzan cosas que no son Error; igual tienen que llegar legibles.
41
+ return { type: "UnknownError", message: textoDe(error) };
42
+ }
43
+ const NEUTRO = {
44
+ attempt: 1,
45
+ limit: 1,
46
+ is_final_attempt: true,
47
+ work_unit_id: null,
48
+ };
49
+ /** Solo devuelve números donde el SDK REALMENTE los sabe. En `alarm` los maneja el repo, en
50
+ * `workflow` viven en el ctx del step y en `queue` en el mensaje: ahí se omite el bloque, porque
51
+ * un valor inventado silencia la alerta terminal. */
52
+ export function retryPorSuperficie(surface) {
53
+ switch (surface) {
54
+ case "worker":
55
+ case "durable_object":
56
+ case "cron":
57
+ return { ...NEUTRO };
58
+ default:
59
+ return undefined;
60
+ }
61
+ }
62
+ // La ingesta exige `attempt`/`limit` >= 1: un 0 (o negativo, o no entero) pasado a mano por
63
+ // CaptureOptions se omite en vez de mandar un 400.
64
+ function enteroPositivo(valor) {
65
+ return valor !== undefined && Number.isInteger(valor) && valor >= 1;
66
+ }
67
+ /** Mapea los números de camelCase (API pública) a snake_case (contrato). */
68
+ export function retryDesdeOpciones(info) {
69
+ const salida = {};
70
+ if (enteroPositivo(info.attempt))
71
+ salida.attempt = info.attempt;
72
+ if (enteroPositivo(info.limit))
73
+ salida.limit = info.limit;
74
+ if (info.isFinalAttempt !== undefined) {
75
+ salida.is_final_attempt = info.isFinalAttempt;
76
+ }
77
+ else if (salida.attempt !== undefined && salida.limit !== undefined) {
78
+ // `>=` y nunca `>`: `limit` son intentos totales, así que con `>` la alerta terminal no
79
+ // se dispararía jamás.
80
+ salida.is_final_attempt = salida.attempt >= salida.limit;
81
+ }
82
+ if (info.workUnitId !== undefined)
83
+ salida.work_unit_id = info.workUnitId;
84
+ return salida;
85
+ }
86
+ export function armarEvento(args) {
87
+ const { opciones } = args;
88
+ const evento = {
89
+ event_id: crypto.randomUUID(),
90
+ seq: nextSeq(),
91
+ timestamp: new Date().toISOString(),
92
+ type: args.tipo,
93
+ severity: opciones.severity ?? args.severityDefault,
94
+ // El agentId de las opciones pisa el de la config: los workers multi-tenant no lo
95
+ // conocen cuando se arma el cliente. `||` y no `??`: el agentId de la config ya se
96
+ // validó no vacío, así que un "" del caller (fila de D1 con NULL) no puede ganarle.
97
+ context: { agent_id: opciones.agentId || args.agentId },
98
+ };
99
+ if (args.mensaje !== undefined) {
100
+ evento.message = truncar(args.mensaje, LIMITES.messageChars);
101
+ }
102
+ if (opciones.workUnit !== undefined)
103
+ evento.context.work_unit = opciones.workUnit;
104
+ if (opciones.traceId !== undefined)
105
+ evento.context.trace_id = opciones.traceId;
106
+ if (opciones.conversationId !== undefined) {
107
+ evento.context.conversation_id = opciones.conversationId;
108
+ }
109
+ if (opciones.requestId !== undefined)
110
+ evento.context.request_id = opciones.requestId;
111
+ if (args.exception !== undefined) {
112
+ const excepcion = { ...args.exception };
113
+ if (excepcion.stacktrace !== undefined) {
114
+ excepcion.stacktrace = truncar(excepcion.stacktrace, LIMITES.stacktraceChars);
115
+ }
116
+ // La ingesta no trunca este campo, pero es el mismo texto que `message` y dejarlo suelto
117
+ // hace que un mensaje enorme se coma el tope de bytes del sobre.
118
+ if (excepcion.message !== undefined) {
119
+ excepcion.message = truncar(excepcion.message, LIMITES.messageChars);
120
+ }
121
+ evento.exception = excepcion;
122
+ }
123
+ const retry = opciones.retry !== undefined
124
+ ? retryDesdeOpciones(opciones.retry)
125
+ : retryPorSuperficie(args.surface);
126
+ if (retry !== undefined)
127
+ evento.retry = retry;
128
+ const attrs = acotarAttributes(opciones.attributes);
129
+ if (attrs !== undefined)
130
+ evento.attributes = attrs;
131
+ // Si va, la ingesta lo usa tal cual en vez de calcular la huella.
132
+ if (opciones.fingerprint !== undefined)
133
+ evento.fingerprint = opciones.fingerprint;
134
+ return evento;
135
+ }
136
+ /** Un sobre por captura, sin batching: el caso es 1 error por invocación, y batchear exigiría un
137
+ * punto de flush, que es justo donde se pierde data. */
138
+ export function armarSobre(args) {
139
+ return {
140
+ sdk: { name: SDK_NAME, version: SDK_VERSION },
141
+ sent_at: new Date().toISOString(),
142
+ // El spread arma un objeto fresco: `Drops` es una interfaz sin índice y TypeScript no la
143
+ // deja pasar directo como `Record<string, number>` (el tipo del sobre, más permisivo a propósito).
144
+ drops: { ...drops() },
145
+ // Perezoso: la primera captura es la que genera el id del isolate.
146
+ session: session(),
147
+ resource: {
148
+ service: args.service,
149
+ client: { organization_id: args.organizationId },
150
+ surface: args.surface,
151
+ },
152
+ notify: args.notify,
153
+ events: [args.evento],
154
+ };
155
+ }
156
+ /** Recorta el sobre hasta que entre en el tope de bytes. NUNCA descarta el evento: un error con
157
+ * stacktrace enorme sigue siendo un error que hay que reportar. Muta el sobre, que es
158
+ * recién armado y de este módulo. */
159
+ export function serializarAcotado(sobre) {
160
+ let body = JSON.stringify(sobre);
161
+ if (bytesDe(body) <= LIMITES.bodyBytes)
162
+ return { body, recortado: false };
163
+ const evento = sobre.events[0];
164
+ // En orden de "lo más grande y lo menos valioso" primero.
165
+ const pasos = [
166
+ () => {
167
+ if (evento.exception?.stacktrace !== undefined) {
168
+ evento.exception.stacktrace = truncar(evento.exception.stacktrace, 1024);
169
+ }
170
+ },
171
+ () => {
172
+ if (evento.exception !== undefined)
173
+ delete evento.exception.stacktrace;
174
+ },
175
+ () => {
176
+ if (evento.attributes !== undefined)
177
+ evento.attributes = {};
178
+ },
179
+ () => {
180
+ if (evento.message !== undefined)
181
+ evento.message = truncar(evento.message, 256);
182
+ },
183
+ ];
184
+ for (const paso of pasos) {
185
+ paso();
186
+ body = JSON.stringify(sobre);
187
+ if (bytesDe(body) <= LIMITES.bodyBytes)
188
+ break;
189
+ }
190
+ // No cambia la política —no se descarta el evento, no se agregan pasos—, solo deja de ser
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).
193
+ const bytesFinales = bytesDe(body);
194
+ if (bytesFinales > LIMITES.bodyBytes) {
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`);
196
+ }
197
+ contarRecortado();
198
+ return { body, recortado: true };
199
+ }
200
+ //# sourceMappingURL=sobre.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sobre.js","sourceRoot":"","sources":["../../src/core/sobre.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,154 @@
1
+ /** Los pesos que usa la ingesta para decidir la alerta: debug 1 < info 2 < warning 3 < error 4 <
2
+ * fatal 5. */
3
+ export declare const SEVERITIES: readonly ["debug", "info", "warning", "error", "fatal"];
4
+ export type Severity = (typeof SEVERITIES)[number];
5
+ /** Las seis superficies del contrato de la ingesta. */
6
+ export declare const SURFACES: readonly ["worker", "durable_object", "workflow", "queue", "alarm", "cron"];
7
+ export type Surface = (typeof SURFACES)[number];
8
+ type Slack = {
9
+ enabled: false;
10
+ } | {
11
+ enabled: true;
12
+ channel: string;
13
+ };
14
+ type Email = {
15
+ enabled: false;
16
+ } | {
17
+ enabled: true;
18
+ to: [string, ...string[]];
19
+ };
20
+ /** Union discriminado y no campos opcionales: los seis errores que la ingesta rechaza con 400 no
21
+ * llegan a compilar. El `[string, ...string[]]` es lo que hace que `to: []` no compile:
22
+ * es un tuple con al menos un elemento, el equivalente en tipos del `.min(1)` de Zod. */
23
+ export type Notify = {
24
+ slack: Extract<Slack, {
25
+ enabled: true;
26
+ }>;
27
+ email?: Email;
28
+ } | {
29
+ slack?: Slack;
30
+ email: Extract<Email, {
31
+ enabled: true;
32
+ }>;
33
+ };
34
+ /** Un evento, con los nombres del contrato tal como los espera la ingesta (snake_case). */
35
+ export interface TelemetryEvent {
36
+ event_id: string;
37
+ seq: number;
38
+ timestamp: string;
39
+ type: "error" | "event";
40
+ severity: Severity;
41
+ message?: string;
42
+ context: {
43
+ agent_id: string;
44
+ work_unit?: string;
45
+ trace_id?: string;
46
+ conversation_id?: string;
47
+ request_id?: string;
48
+ };
49
+ retry?: {
50
+ attempt?: number;
51
+ limit?: number;
52
+ is_final_attempt?: boolean;
53
+ work_unit_id?: string | null;
54
+ };
55
+ exception?: {
56
+ type?: string;
57
+ message?: string;
58
+ stacktrace?: string;
59
+ };
60
+ attributes?: Record<string, string | number | boolean>;
61
+ fingerprint?: string[];
62
+ }
63
+ /** El sobre: un evento por captura, sin batching. */
64
+ export interface Envelope {
65
+ sdk: {
66
+ name: string;
67
+ version: string;
68
+ };
69
+ sent_at: string;
70
+ drops: Record<string, number>;
71
+ session: string;
72
+ resource: {
73
+ service: {
74
+ name: string;
75
+ version?: string;
76
+ environment?: string;
77
+ };
78
+ client: {
79
+ organization_id: string;
80
+ };
81
+ surface: Surface;
82
+ };
83
+ notify: Notify;
84
+ events: [TelemetryEvent];
85
+ }
86
+ /** Los números del reintento, en camelCase porque es API pública; `sobre.ts` los mapea a
87
+ * snake_case. Si no viene `isFinalAttempt` se calcula como `attempt >= limit`. */
88
+ export interface RetryInfo {
89
+ attempt?: number;
90
+ limit?: number;
91
+ isFinalAttempt?: boolean;
92
+ workUnitId?: string | null;
93
+ }
94
+ export interface CaptureOptions {
95
+ workUnit?: string;
96
+ traceId?: string;
97
+ conversationId?: string;
98
+ requestId?: string;
99
+ severity?: Severity;
100
+ attributes?: Record<string, string | number | boolean>;
101
+ retry?: RetryInfo;
102
+ fingerprint?: string[];
103
+ /** Overrides por evento, para los workers multi-tenant que no conocen estos valores cuando
104
+ * se arma la config. Sin ellos, todo iría bajo un id genérico y todas las alertas
105
+ * caerían en un solo canal. */
106
+ agentId?: string;
107
+ organizationId?: string;
108
+ notify?: Notify;
109
+ }
110
+ /** Pide lo MÍNIMO que el SDK usa, y a propósito no es `ExecutionContext`: tiparlo así obligaría
111
+ * a depender de @cloudflare/workers-types, y un desajuste de versiones rompería la compilación
112
+ * del cliente sin ninguna causa funcional. El contrapeso es que este tipo también deja
113
+ * pasar la copia rota del ctx, y por eso hay un chequeo en runtime. */
114
+ export interface CtxLike {
115
+ waitUntil?: (p: Promise<unknown>) => void;
116
+ }
117
+ export interface TelemetryConfig {
118
+ service: {
119
+ name: string;
120
+ version?: string;
121
+ environment?: string;
122
+ };
123
+ surface: Surface;
124
+ organizationId: string;
125
+ agentId: string;
126
+ apiKey: string;
127
+ notify: Notify;
128
+ ctx?: CtxLike;
129
+ /** SOLO desarrollo local. En producción la URL es constante del paquete. */
130
+ ingestUrl?: string;
131
+ scrub?: string[];
132
+ beforeSend?: (evento: TelemetryEvent) => TelemetryEvent | null;
133
+ debug?: boolean;
134
+ /** El MISMO número, con el mismo nombre, que el `max_retries` del wrangler.jsonc del
135
+ * consumer. El SDK le suma 1 porque son los reintentos DESPUÉS de la primera entrega, y
136
+ * copiarlo crudo produce un falso "falla definitiva". */
137
+ queueMaxRetries?: number;
138
+ }
139
+ /** La config de `withTelemetry`: sin `surface`, que se deduce del nombre del handler, y sin
140
+ * `ctx`, que lo provee el handler. Los `never` los hacen errores de compilación. */
141
+ export type HandlerTelemetryConfig = Omit<TelemetryConfig, "surface" | "ctx"> & {
142
+ surface?: never;
143
+ ctx?: never;
144
+ };
145
+ export interface TelemetryClient {
146
+ /** Devuelve void, nunca una promesa, y nunca lanza. */
147
+ captureException(error: unknown, options?: CaptureOptions): void;
148
+ /** Para el estado D, donde no hay ningún objeto Error que pasar. */
149
+ captureEvent(message: string, options?: CaptureOptions): void;
150
+ /** Envuelve una tool de MCP: captura y re-lanza el mismo error. */
151
+ withTool<Args extends unknown[], R>(nombre: string, fn: (...args: Args) => R | Promise<R>): (...args: Args) => Promise<R>;
152
+ }
153
+ export {};
154
+ //# sourceMappingURL=tipos.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tipos.d.ts","sourceRoot":"","sources":["../../src/core/tipos.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,6 @@
1
+ /** Los pesos que usa la ingesta para decidir la alerta: debug 1 < info 2 < warning 3 < error 4 <
2
+ * fatal 5. */
3
+ export const SEVERITIES = ["debug", "info", "warning", "error", "fatal"];
4
+ /** Las seis superficies del contrato de la ingesta. */
5
+ export const SURFACES = ["worker", "durable_object", "workflow", "queue", "alarm", "cron"];
6
+ //# sourceMappingURL=tipos.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tipos.js","sourceRoot":"","sources":["../../src/core/tipos.ts"],"names":[],"mappings":"AAAA;eACe;AACf,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAGlF,uDAAuD;AACvD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC"}
@@ -0,0 +1,24 @@
1
+ import type { CtxLike } from "./tipos.js";
2
+ /** El texto completo del aviso: dice qué pasó, qué consecuencia tiene y cómo arreglarlo. Sin este
3
+ * aviso el evento se pierde en silencio en `worker` y `queue`, que es exactamente el modo de
4
+ * falla que este paquete existe para eliminar. */
5
+ export declare const AVISO_CTX_ROTO: string;
6
+ export interface CtxUsable {
7
+ waitUntil: (p: Promise<unknown>) => void;
8
+ }
9
+ /** Lo prueba UNA vez, con una promesa ya resuelta. No alcanza con preguntar si `waitUntil`
10
+ * existe: la copia del ctx hereda el método pero no la identidad del objeto nativo, así que
11
+ * existe y tira `Illegal invocation` al invocarlo. */
12
+ export declare function probarCtx(ctx: CtxLike | undefined, avisar: () => void): CtxUsable | null;
13
+ export interface ArgsEnvio {
14
+ body: string;
15
+ apiKey: string;
16
+ url: string;
17
+ ctx: CtxUsable | null;
18
+ debug: boolean;
19
+ avisarCtxRoto: () => void;
20
+ }
21
+ /** Dispara el POST y no espera nada. No reintenta, no lanza, y la promesa que le pasa a
22
+ * `waitUntil` nunca rechaza. */
23
+ export declare function enviar(args: ArgsEnvio): void;
24
+ //# sourceMappingURL=transporte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"transporte.d.ts","sourceRoot":"","sources":["../../src/core/transporte.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;mDAEmD;AACnD,eAAO,MAAM,cAAc,QAMhB,CAAC;AAEZ,MAAM,WAAW,SAAS;IACzB,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACzC;AAED;;uDAEuD;AACvD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,SAAS,GAAG,IAAI,CASxF;AAkBD,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;iCACiC;AACjC,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAiC5C"}
@@ -0,0 +1,70 @@
1
+ import { contarCompletado, contarDisparado, contarFallado } from "./contadores.js";
2
+ /** El texto completo del aviso: dice qué pasó, qué consecuencia tiene y cómo arreglarlo. Sin este
3
+ * aviso el evento se pierde en silencio en `worker` y `queue`, que es exactamente el modo de
4
+ * falla que este paquete existe para eliminar. */
5
+ export const AVISO_CTX_ROTO = [
6
+ "[delta-sdk] El `ctx` recibido tiene `waitUntil` pero no es invocable: parece una copia",
7
+ "hecha con spread u Object.create (patrón habitual para inyectar `props` en un McpAgent).",
8
+ "Los eventos se van a PERDER en surface 'worker' y 'queue'. Pasale a createTelemetry el",
9
+ "ExecutionContext original del handler, no la copia — podés seguir usando la copia para",
10
+ "el McpAgent, son dos consumidores distintos.",
11
+ ].join(" ");
12
+ /** Lo prueba UNA vez, con una promesa ya resuelta. No alcanza con preguntar si `waitUntil`
13
+ * existe: la copia del ctx hereda el método pero no la identidad del objeto nativo, así que
14
+ * existe y tira `Illegal invocation` al invocarlo. */
15
+ export function probarCtx(ctx, avisar) {
16
+ if (typeof ctx?.waitUntil !== "function")
17
+ return null;
18
+ try {
19
+ ctx.waitUntil(Promise.resolve());
20
+ return ctx;
21
+ }
22
+ catch {
23
+ avisar();
24
+ return null;
25
+ }
26
+ }
27
+ /** El 401 no queda detrás de `debug`: es config rota y hay que verla. Los demás status solo
28
+ * hablan en debug, porque el SDK no reintenta en ninguno. */
29
+ function reportar(status, debug) {
30
+ if (status === 401) {
31
+ console.error("[delta-sdk] la ingesta rechazó el bearer (401): revisá el apiKey del env, no se va a reportar nada");
32
+ return;
33
+ }
34
+ if (debug && status >= 400) {
35
+ console.warn(`[delta-sdk] la ingesta respondió ${status}; el evento se descarta sin reintentar`);
36
+ }
37
+ }
38
+ /** Dispara el POST y no espera nada. No reintenta, no lanza, y la promesa que le pasa a
39
+ * `waitUntil` nunca rechaza. */
40
+ export function enviar(args) {
41
+ contarDisparado();
42
+ const promesa = fetch(args.url, {
43
+ method: "POST",
44
+ headers: {
45
+ Authorization: `Bearer ${args.apiKey}`,
46
+ "Content-Type": "application/json",
47
+ },
48
+ body: args.body,
49
+ })
50
+ .then((respuesta) => {
51
+ // Cualquier status es "salió y contestaron": el 429 y el 503 no son pérdida.
52
+ contarCompletado();
53
+ reportar(respuesta.status, args.debug);
54
+ }, () => {
55
+ // Solo la red y el DNS llegan acá. Nunca se re-lanza.
56
+ contarFallado();
57
+ })
58
+ .catch(() => {
59
+ // Red final. Que la promesa resuelva siempre es lo que impide que un fallo del SDK
60
+ // marque la invocación del cliente como excepción.
61
+ });
62
+ try {
63
+ args.ctx?.waitUntil(promesa);
64
+ }
65
+ catch {
66
+ // Segundo chequeo, por las dudas: el SDK nunca lanza. La promesa queda flotando.
67
+ args.avisarCtxRoto();
68
+ }
69
+ }
70
+ //# sourceMappingURL=transporte.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"transporte.js","sourceRoot":"","sources":["../../src/core/transporte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGnF;;mDAEmD;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,wFAAwF;IACxF,0FAA0F;IAC1F,wFAAwF;IACxF,wFAAwF;IACxF,8CAA8C;CAC9C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAMZ;;uDAEuD;AACvD,MAAM,UAAU,SAAS,CAAC,GAAwB,EAAE,MAAkB;IACrE,IAAI,OAAO,GAAG,EAAE,SAAS,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,CAAC;QACJ,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACjC,OAAO,GAAgB,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAED;8DAC8D;AAC9D,SAAS,QAAQ,CAAC,MAAc,EAAE,KAAc;IAC/C,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CACZ,oGAAoG,CACpG,CAAC;QACF,OAAO;IACR,CAAC;IACD,IAAI,KAAK,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAC5B,OAAO,CAAC,IAAI,CACX,oCAAoC,MAAM,wCAAwC,CAClF,CAAC;IACH,CAAC;AACF,CAAC;AAWD;iCACiC;AACjC,MAAM,UAAU,MAAM,CAAC,IAAe;IACrC,eAAe,EAAE,CAAC;IAElB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE;QAC/B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACR,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;YACtC,cAAc,EAAE,kBAAkB;SAClC;QACD,IAAI,EAAE,IAAI,CAAC,IAAI;KACf,CAAC;SACA,IAAI,CACJ,CAAC,SAAS,EAAE,EAAE;QACb,6EAA6E;QAC7E,gBAAgB,EAAE,CAAC;QACnB,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC,EACD,GAAG,EAAE;QACJ,sDAAsD;QACtD,aAAa,EAAE,CAAC;IACjB,CAAC,CACD;SACA,KAAK,CAAC,GAAG,EAAE;QACX,mFAAmF;QACnF,mDAAmD;IACpD,CAAC,CAAC,CAAC;IAEJ,IAAI,CAAC;QACJ,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACR,iFAAiF;QACjF,IAAI,CAAC,aAAa,EAAE,CAAC;IACtB,CAAC;AACF,CAAC"}
@@ -0,0 +1,2 @@
1
+ export type { Envelope, Notify, Severity, Surface, TelemetryEvent, } from "./core/tipos.js";
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,OAAO,EACP,cAAc,GACd,MAAM,iBAAiB,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
@@ -0,0 +1,8 @@
1
+ import type { TelemetryClient, TelemetryConfig } from "../core/tipos.js";
2
+ /** El núcleo explícito, y el camino principal: los dos wrappers se construyen sobre esto y
3
+ * ninguno puede hacer nada que esto no permita.
4
+ *
5
+ * Va llamado DENTRO de una invocación —`init()` de un Durable Object, un handler— y nunca a
6
+ * nivel de módulo: un valor aleatorio en el scope global hace fallar el deploy. */
7
+ export declare function createTelemetry(config: TelemetryConfig): TelemetryClient;
8
+ //# sourceMappingURL=captura.d.ts.map
@@ -0,0 +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"}