@laburen/delta-sdk 1.3.0 → 1.5.0-canary.10

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 (150) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +3 -0
  3. package/dist/core/config.d.ts +12 -12
  4. package/dist/core/config.d.ts.map +1 -1
  5. package/dist/core/config.js +88 -88
  6. package/dist/core/config.js.map +1 -1
  7. package/dist/core/{constantes.d.ts → constants.d.ts} +3 -3
  8. package/dist/core/constants.d.ts.map +1 -0
  9. package/dist/core/{constantes.js → constants.js} +3 -3
  10. package/dist/core/constants.js.map +1 -0
  11. package/dist/core/{contadores.d.ts → counters.d.ts} +12 -11
  12. package/dist/core/counters.d.ts.map +1 -0
  13. package/dist/core/counters.js +53 -0
  14. package/dist/core/counters.js.map +1 -0
  15. package/dist/core/{sobre.d.ts → envelope.d.ts} +17 -17
  16. package/dist/core/envelope.d.ts.map +1 -0
  17. package/dist/core/envelope.js +198 -0
  18. package/dist/core/envelope.js.map +1 -0
  19. package/dist/core/scrubbing.d.ts +4 -4
  20. package/dist/core/scrubbing.d.ts.map +1 -1
  21. package/dist/core/scrubbing.js +38 -38
  22. package/dist/core/scrubbing.js.map +1 -1
  23. package/dist/core/{sesion.d.ts → session.d.ts} +2 -2
  24. package/dist/core/session.d.ts.map +1 -0
  25. package/dist/core/{sesion.js → session.js} +2 -2
  26. package/dist/core/session.js.map +1 -0
  27. package/dist/core/{transporte.d.ts → transport.d.ts} +9 -9
  28. package/dist/core/transport.d.ts.map +1 -0
  29. package/dist/core/{transporte.js → transport.js} +15 -15
  30. package/dist/core/transport.js.map +1 -0
  31. package/dist/core/{tipos.d.ts → types.d.ts} +4 -4
  32. package/dist/core/{tipos.d.ts.map → types.d.ts.map} +1 -1
  33. package/dist/core/{tipos.js → types.js} +1 -1
  34. package/dist/core/{tipos.js.map → types.js.map} +1 -1
  35. package/dist/index.d.ts +1 -1
  36. package/dist/platform/client.d.ts +8 -0
  37. package/dist/platform/client.d.ts.map +1 -0
  38. package/dist/platform/client.js +30 -0
  39. package/dist/platform/client.js.map +1 -0
  40. package/dist/platform/core/errors.d.ts +150 -0
  41. package/dist/platform/core/errors.d.ts.map +1 -0
  42. package/dist/platform/core/errors.js +265 -0
  43. package/dist/platform/core/errors.js.map +1 -0
  44. package/dist/platform/core/oauth.d.ts +37 -0
  45. package/dist/platform/core/oauth.d.ts.map +1 -0
  46. package/dist/platform/core/oauth.js +144 -0
  47. package/dist/platform/core/oauth.js.map +1 -0
  48. package/dist/platform/core/pagination.d.ts +30 -0
  49. package/dist/platform/core/pagination.d.ts.map +1 -0
  50. package/dist/platform/core/pagination.js +44 -0
  51. package/dist/platform/core/pagination.js.map +1 -0
  52. package/dist/platform/core/request.d.ts +6 -0
  53. package/dist/platform/core/request.d.ts.map +1 -0
  54. package/dist/platform/core/request.js +24 -0
  55. package/dist/platform/core/request.js.map +1 -0
  56. package/dist/platform/core/send.d.ts +36 -0
  57. package/dist/platform/core/send.d.ts.map +1 -0
  58. package/dist/platform/core/send.js +171 -0
  59. package/dist/platform/core/send.js.map +1 -0
  60. package/dist/platform/core/sse.d.ts +8 -0
  61. package/dist/platform/core/sse.d.ts.map +1 -0
  62. package/dist/platform/core/sse.js +72 -0
  63. package/dist/platform/core/sse.js.map +1 -0
  64. package/dist/platform/core/stream.d.ts +21 -0
  65. package/dist/platform/core/stream.d.ts.map +1 -0
  66. package/dist/platform/core/stream.js +268 -0
  67. package/dist/platform/core/stream.js.map +1 -0
  68. package/dist/platform/generated/resources.d.ts +120 -0
  69. package/dist/platform/generated/resources.d.ts.map +1 -0
  70. package/dist/platform/generated/resources.js +65 -0
  71. package/dist/platform/generated/resources.js.map +1 -0
  72. package/dist/platform/generated/schemas.d.ts +78 -0
  73. package/dist/platform/generated/schemas.d.ts.map +1 -0
  74. package/dist/platform/generated/schemas.js +2 -0
  75. package/dist/platform/generated/schemas.js.map +1 -0
  76. package/dist/platform/generated/types.d.ts +5167 -0
  77. package/dist/platform/generated/types.d.ts.map +1 -0
  78. package/dist/platform/generated/types.js +6 -0
  79. package/dist/platform/generated/types.js.map +1 -0
  80. package/dist/platform/index.d.ts +9 -0
  81. package/dist/platform/index.d.ts.map +1 -0
  82. package/dist/platform/index.js +7 -0
  83. package/dist/platform/index.js.map +1 -0
  84. package/dist/telemetry/{captura.d.ts → capture.d.ts} +3 -3
  85. package/dist/telemetry/capture.d.ts.map +1 -0
  86. package/dist/telemetry/{captura.js → capture.js} +54 -54
  87. package/dist/telemetry/capture.js.map +1 -0
  88. package/dist/telemetry/index.d.ts +2 -2
  89. package/dist/telemetry/index.js +1 -1
  90. package/dist/telemetry/{tipos.d.ts → types.d.ts} +2 -2
  91. package/dist/telemetry/types.d.ts.map +1 -0
  92. package/dist/telemetry/types.js +2 -0
  93. package/dist/telemetry/types.js.map +1 -0
  94. package/dist/telemetry/with-telemetry.d.ts +9 -9
  95. package/dist/telemetry/with-telemetry.d.ts.map +1 -1
  96. package/dist/telemetry/with-telemetry.js +31 -31
  97. package/dist/telemetry/with-telemetry.js.map +1 -1
  98. package/dist/telemetry/with-tool.d.ts +2 -2
  99. package/dist/telemetry/with-tool.d.ts.map +1 -1
  100. package/dist/telemetry/with-tool.js +3 -3
  101. package/dist/telemetry/with-tool.js.map +1 -1
  102. package/docs/platform/guide.md +554 -0
  103. package/docs/telemetry/que-se-manda.md +2 -2
  104. package/docs/telemetry/troubleshooting.md +1 -1
  105. package/package.json +15 -5
  106. package/src/core/config.ts +81 -83
  107. package/src/core/{constantes.ts → constants.ts} +2 -2
  108. package/src/core/counters.ts +72 -0
  109. package/src/core/envelope.ts +234 -0
  110. package/src/core/scrubbing.ts +41 -41
  111. package/src/core/{sesion.ts → session.ts} +1 -1
  112. package/src/core/{transporte.ts → transport.ts} +20 -20
  113. package/src/core/{tipos.ts → types.ts} +3 -3
  114. package/src/index.ts +1 -1
  115. package/src/platform/client.ts +32 -0
  116. package/src/platform/core/errors.ts +348 -0
  117. package/src/platform/core/oauth.ts +201 -0
  118. package/src/platform/core/pagination.ts +67 -0
  119. package/src/platform/core/request.ts +27 -0
  120. package/src/platform/core/send.ts +212 -0
  121. package/src/platform/core/sse.ts +68 -0
  122. package/src/platform/core/stream.ts +314 -0
  123. package/src/platform/generated/resources.ts +192 -0
  124. package/src/platform/generated/schemas.ts +79 -0
  125. package/src/platform/generated/types.ts +5167 -0
  126. package/src/platform/index.ts +45 -0
  127. package/src/telemetry/{captura.ts → capture.ts} +57 -57
  128. package/src/telemetry/index.ts +2 -2
  129. package/src/telemetry/{tipos.ts → types.ts} +1 -1
  130. package/src/telemetry/with-telemetry.ts +51 -54
  131. package/src/telemetry/with-tool.ts +5 -5
  132. package/dist/core/constantes.d.ts.map +0 -1
  133. package/dist/core/constantes.js.map +0 -1
  134. package/dist/core/contadores.d.ts.map +0 -1
  135. package/dist/core/contadores.js +0 -53
  136. package/dist/core/contadores.js.map +0 -1
  137. package/dist/core/sesion.d.ts.map +0 -1
  138. package/dist/core/sesion.js.map +0 -1
  139. package/dist/core/sobre.d.ts.map +0 -1
  140. package/dist/core/sobre.js +0 -200
  141. package/dist/core/sobre.js.map +0 -1
  142. package/dist/core/transporte.d.ts.map +0 -1
  143. package/dist/core/transporte.js.map +0 -1
  144. package/dist/telemetry/captura.d.ts.map +0 -1
  145. package/dist/telemetry/captura.js.map +0 -1
  146. package/dist/telemetry/tipos.d.ts.map +0 -1
  147. package/dist/telemetry/tipos.js +0 -2
  148. package/dist/telemetry/tipos.js.map +0 -1
  149. package/src/core/contadores.ts +0 -71
  150. package/src/core/sobre.ts +0 -236
@@ -0,0 +1,201 @@
1
+ import type { components } from "../generated/types.js";
2
+ import {
3
+ isLaburenConnectionError,
4
+ isLaburenOAuthError,
5
+ LaburenAbortError,
6
+ LaburenConnectionError,
7
+ LaburenOAuthError,
8
+ LaburenTimeoutError,
9
+ } from "./errors.js";
10
+ import { DEFAULT_BASE_URL } from "./send.js";
11
+
12
+ type Schemas = components["schemas"];
13
+
14
+ /** Opciones comunes de las funciones de login; ninguna lleva token ni reintenta. */
15
+ export interface OAuthCallOptions {
16
+ baseUrl?: string;
17
+ fetch?: typeof fetch;
18
+ signal?: AbortSignal;
19
+ /** Milisegundos por pedido (default 30 000); en `waitForDeviceToken` vale para cada consulta, no para la espera total. */
20
+ timeout?: number;
21
+ }
22
+
23
+ export interface StartDeviceLoginOptions extends OAuthCallOptions {
24
+ /** Texto libre (máx. 200) que la pantalla de aprobación le muestra a quien aprueba. */
25
+ clientInfo?: string;
26
+ }
27
+
28
+ export interface WaitForDeviceTokenOptions extends OAuthCallOptions {
29
+ deviceCode: string;
30
+ /** Segundos entre intentos, tal cual lo devolvió `startDeviceLogin`. */
31
+ interval: number;
32
+ /** Segundos de vida del código, tal cual lo devolvió `startDeviceLogin`. */
33
+ expiresIn: number;
34
+ }
35
+
36
+ export interface RefreshTokenOptions extends OAuthCallOptions {
37
+ refreshToken: string;
38
+ }
39
+
40
+ export interface RevokeTokenOptions extends OAuthCallOptions {
41
+ token: string;
42
+ }
43
+
44
+ const DEFAULT_TIMEOUT_MS = 30_000;
45
+ const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
46
+ /** RFC 8628: ante `slow_down` el intervalo sube 5 segundos. */
47
+ const SLOW_DOWN_STEP_SECONDS = 5;
48
+
49
+ function isRecord(value: unknown): value is Record<string, unknown> {
50
+ return typeof value === "object" && value !== null && !Array.isArray(value);
51
+ }
52
+
53
+ /** Manda un POST JSON sin `authorization`; un error de la API sale como `LaburenOAuthError`. */
54
+ async function postOAuth<T>(path: string, body: unknown, opts: OAuthCallOptions): Promise<T> {
55
+ const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
56
+ const doFetch = opts.fetch ?? fetch;
57
+
58
+ const timeoutMs = opts.timeout ?? DEFAULT_TIMEOUT_MS;
59
+ const callerSignal = opts.signal;
60
+ // Un controller por pedido: junta el corte del llamador con el timeout propio.
61
+ const controller = new AbortController();
62
+ let timedOut = false;
63
+ const onCallerAbort = () => controller.abort(callerSignal?.reason);
64
+ if (callerSignal?.aborted) controller.abort(callerSignal.reason);
65
+ callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
66
+ const timer = setTimeout(() => {
67
+ timedOut = true;
68
+ controller.abort();
69
+ }, timeoutMs);
70
+
71
+ let response: Response;
72
+ let parsed: unknown;
73
+ try {
74
+ response = await doFetch(`${baseUrl}${path}`, {
75
+ method: "POST",
76
+ headers: { "content-type": "application/json", accept: "application/json" },
77
+ body: JSON.stringify(body),
78
+ signal: controller.signal,
79
+ });
80
+ try {
81
+ parsed = await response.json();
82
+ } catch {
83
+ parsed = undefined;
84
+ }
85
+ } catch (cause) {
86
+ // Si cortó el llamador, sale `LaburenAbortError` y no un error de red.
87
+ if (callerSignal?.aborted) throw new LaburenAbortError({ cause: callerSignal.reason });
88
+ if (timedOut) {
89
+ throw new LaburenTimeoutError(`The login server did not respond within ${timeoutMs} ms.`, {
90
+ cause,
91
+ });
92
+ }
93
+ throw new LaburenConnectionError("Could not connect to the login server.", { cause });
94
+ } finally {
95
+ clearTimeout(timer);
96
+ callerSignal?.removeEventListener("abort", onCallerAbort);
97
+ }
98
+
99
+ if (!response.ok) {
100
+ // Sin cuerpo RFC (proxy, HTML, corte) se lo trata como falla del servidor.
101
+ const error =
102
+ isRecord(parsed) && typeof parsed.error === "string" ? parsed.error : "server_error";
103
+ const description =
104
+ isRecord(parsed) && typeof parsed.error_description === "string"
105
+ ? parsed.error_description
106
+ : null;
107
+ throw new LaburenOAuthError({ error, description, status: response.status });
108
+ }
109
+ if (parsed === undefined) {
110
+ throw new LaburenOAuthError({
111
+ error: "server_error",
112
+ description: "The response is not JSON.",
113
+ status: response.status,
114
+ });
115
+ }
116
+ return parsed as T;
117
+ }
118
+
119
+ /** Inicia el login por device code (RFC 8628): devuelve el código para que la persona apruebe en el navegador. */
120
+ export function startDeviceLogin(
121
+ opts: StartDeviceLoginOptions = {},
122
+ ): Promise<Schemas["DeviceAuthorization"]> {
123
+ const body = opts.clientInfo === undefined ? {} : { client_info: opts.clientInfo };
124
+ return postOAuth("/oauth/device", body, opts);
125
+ }
126
+
127
+ /** Espera `ms` milisegundos; si se aborta `signal` rechaza con `LaburenAbortError` y limpia el timer. */
128
+ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
129
+ return new Promise((resolve, reject) => {
130
+ if (signal?.aborted) {
131
+ reject(new LaburenAbortError({ cause: signal.reason }));
132
+ return;
133
+ }
134
+ const onAbort = () => {
135
+ clearTimeout(timer);
136
+ reject(new LaburenAbortError({ cause: signal?.reason }));
137
+ };
138
+ const timer = setTimeout(() => {
139
+ signal?.removeEventListener("abort", onAbort);
140
+ resolve();
141
+ }, ms);
142
+ signal?.addEventListener("abort", onAbort, { once: true });
143
+ });
144
+ }
145
+
146
+ /** Consulta cada `interval` segundos hasta que la persona aprueba; corta con `LaburenOAuthError` si se deniega o vence. */
147
+ export async function waitForDeviceToken(
148
+ opts: WaitForDeviceTokenOptions,
149
+ ): Promise<Schemas["OAuthToken"]> {
150
+ const deadline = Date.now() + opts.expiresIn * 1000;
151
+ let intervalSeconds = opts.interval;
152
+
153
+ for (;;) {
154
+ const waitMs = intervalSeconds * 1000;
155
+ // Si el próximo intento caería pasado el vencimiento, se espera hasta el vencimiento y se corta.
156
+ if (Date.now() + waitMs >= deadline) {
157
+ await sleep(Math.max(0, deadline - Date.now()), opts.signal);
158
+ throw new LaburenOAuthError({
159
+ error: "expired_token",
160
+ description: "The device code expired.",
161
+ status: 400,
162
+ });
163
+ }
164
+ await sleep(waitMs, opts.signal);
165
+ try {
166
+ return await postOAuth<Schemas["OAuthToken"]>(
167
+ "/oauth/token",
168
+ { grant_type: DEVICE_GRANT_TYPE, device_code: opts.deviceCode },
169
+ opts,
170
+ );
171
+ } catch (error) {
172
+ // Un corte de red o un timeout en una consulta no tira el login: se espera más y se reintenta.
173
+ // El vencimiento lo corta el chequeo del principio del loop.
174
+ if (isLaburenConnectionError(error)) {
175
+ intervalSeconds += SLOW_DOWN_STEP_SECONDS;
176
+ continue;
177
+ }
178
+ if (!isLaburenOAuthError(error)) throw error;
179
+ if (error.error === "authorization_pending") continue;
180
+ if (error.error === "slow_down") {
181
+ intervalSeconds += SLOW_DOWN_STEP_SECONDS;
182
+ continue;
183
+ }
184
+ throw error;
185
+ }
186
+ }
187
+ }
188
+
189
+ /** Cambia un refresh token por un access token nuevo. */
190
+ export function refreshToken(opts: RefreshTokenOptions): Promise<Schemas["OAuthToken"]> {
191
+ return postOAuth(
192
+ "/oauth/token",
193
+ { grant_type: "refresh_token", refresh_token: opts.refreshToken },
194
+ opts,
195
+ );
196
+ }
197
+
198
+ /** Revoca un access o refresh token (RFC 7009); la API siempre contesta 200. */
199
+ export async function revokeToken(opts: RevokeTokenOptions): Promise<void> {
200
+ await postOAuth("/oauth/revoke", { token: opts.token }, opts);
201
+ }
@@ -0,0 +1,67 @@
1
+ /** Una página de una lista del contrato. */
2
+ export interface Page<T> {
3
+ data: T[];
4
+ has_more: boolean;
5
+ first_id: string | null;
6
+ last_id: string | null;
7
+ }
8
+
9
+ /** Cursor de un pedido paginado: hacia adelante con `after_id`, hacia atrás con `before_id`. */
10
+ export interface PageCursor {
11
+ after_id?: string;
12
+ before_id?: string;
13
+ }
14
+
15
+ /**
16
+ * Resultado de una lista paginada: `await` da la primera página y `for await` recorre todos los items.
17
+ * No pide nada al construirse; la primera página se pide una sola vez, en el primer `await` o `for await`.
18
+ */
19
+ export class PagePromise<T> implements PromiseLike<Page<T>>, AsyncIterable<T> {
20
+ /** Lo que hace que `Object.prototype.toString` y TypeScript lo traten como una `Promise`. */
21
+ readonly [Symbol.toStringTag] = "PagePromise";
22
+ #first: Promise<Page<T>> | undefined;
23
+ readonly #fetchPage: (cursor: PageCursor) => Promise<Page<T>>;
24
+ readonly #initial: PageCursor;
25
+
26
+ constructor(fetchPage: (cursor: PageCursor) => Promise<Page<T>>, initial: PageCursor) {
27
+ this.#fetchPage = fetchPage;
28
+ this.#initial = initial;
29
+ }
30
+
31
+ #firstPage(): Promise<Page<T>> {
32
+ this.#first ??= this.#fetchPage(this.#initial);
33
+ return this.#first;
34
+ }
35
+
36
+ // biome-ignore lint/suspicious/noThenProperty: es un thenable a propósito, para que `await` dé la primera página
37
+ then<R1 = Page<T>, R2 = never>(
38
+ onfulfilled?: ((value: Page<T>) => R1 | PromiseLike<R1>) | null,
39
+ onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
40
+ ): Promise<R1 | R2> {
41
+ return this.#firstPage().then(onfulfilled, onrejected);
42
+ }
43
+
44
+ /** Atrapa el error de la primera página; igual que en una promesa. */
45
+ catch<R = never>(
46
+ onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null,
47
+ ): Promise<Page<T> | R> {
48
+ return this.#firstPage().catch(onrejected);
49
+ }
50
+
51
+ /** Corre `onfinally` cuando la primera página terminó, bien o mal. */
52
+ finally(onfinally?: (() => void) | null): Promise<Page<T>> {
53
+ return this.#firstPage().finally(onfinally);
54
+ }
55
+
56
+ /** Recorre todos los items; corta si hay más páginas pero falta el cursor para seguir. */
57
+ async *[Symbol.asyncIterator](): AsyncIterator<T> {
58
+ const backwards = this.#initial.before_id !== undefined;
59
+ let page = await this.#firstPage();
60
+ while (true) {
61
+ yield* page.data;
62
+ const next = backwards ? page.first_id : page.last_id;
63
+ if (!page.has_more || next === null) return;
64
+ page = await this.#fetchPage(backwards ? { before_id: next } : { after_id: next });
65
+ }
66
+ }
67
+ }
@@ -0,0 +1,27 @@
1
+ import type { Call } from "../generated/resources.js";
2
+ import { LaburenApiError } from "./errors.js";
3
+ import { type PlatformConfig, parseJson, sendWithRetries } from "./send.js";
4
+ import { openStream } from "./stream.js";
5
+
6
+ // Se reexportan para quien ya importaba estos nombres desde acá (por ejemplo lo generado).
7
+ export { DEFAULT_BASE_URL, type PlatformConfig, type RequestOptions } from "./send.js";
8
+
9
+ /** Lee el cuerpo de una respuesta exitosa como JSON; si no lo es, lanza `LaburenApiError`. */
10
+ async function readJson(response: Response): Promise<unknown> {
11
+ const text = await response.text();
12
+ const parsed = text === "" ? { ok: true as const, value: undefined } : parseJson(text);
13
+ if (parsed.ok) return parsed.value;
14
+ throw new LaburenApiError({
15
+ status: response.status,
16
+ message: `Successful response that is not JSON (status ${response.status}).`,
17
+ requestId: response.headers.get("request-id"),
18
+ });
19
+ }
20
+
21
+ /** Crea la función que hace el pedido de cada operación; todos los métodos de la puerta pasan por acá. */
22
+ export function createCall(config: PlatformConfig): Call {
23
+ return (spec, pathValues, params, options) =>
24
+ spec.stream
25
+ ? openStream(config, spec, pathValues, params, options)
26
+ : sendWithRetries(config, spec, pathValues, params, options, readJson);
27
+ }
@@ -0,0 +1,212 @@
1
+ // Lo que comparten `request.ts` (operaciones JSON) y `stream.ts` (operaciones de stream): el pedido con reintentos.
2
+ import type { OperationSpec } from "../generated/resources.js";
3
+ import {
4
+ apiErrorFromResponse,
5
+ isLaburenApiError,
6
+ LaburenAbortError,
7
+ LaburenArgumentError,
8
+ LaburenConnectionError,
9
+ LaburenTimeoutError,
10
+ } from "./errors.js";
11
+
12
+ /** Opciones por llamada que aceptan todos los métodos de la puerta. */
13
+ export interface RequestOptions {
14
+ organization?: string;
15
+ /** Milisegundos por intento, no por llamada: el peor caso es (maxRetries + 1) × timeout más las esperas entre reintentos. Lo que tarde la función `token` queda afuera. Orden: esta llamada, el contrato de la operación, el cliente, 30 s. */
16
+ timeout?: number;
17
+ maxRetries?: number;
18
+ /** Se ignora en una operación que no es idempotente: no se manda y el pedido no se reintenta. Un texto vacío se reemplaza por un UUID. */
19
+ idempotencyKey?: string;
20
+ signal?: AbortSignal;
21
+ }
22
+
23
+ /** Configuración del cliente de la puerta; cada campo opcional tiene su default. */
24
+ export interface PlatformConfig {
25
+ token: string | (() => Promise<string>);
26
+ organization?: string;
27
+ baseUrl?: string;
28
+ /** Milisegundos por intento, no por llamada: el peor caso es (maxRetries + 1) × timeout más las esperas entre reintentos. Lo que tarde la función `token` queda afuera. Orden: la llamada, el `x-laburen-timeout-ms` del contrato para esa operación, este valor del cliente, 30 s. */
29
+ timeout?: number;
30
+ maxRetries?: number;
31
+ fetch?: typeof fetch;
32
+ }
33
+
34
+ export const DEFAULT_BASE_URL = "https://dashboard.laburen.com/api/platform/v1";
35
+ const DEFAULT_TIMEOUT_MS = 30_000;
36
+ const DEFAULT_MAX_RETRIES = 2;
37
+ const MAX_RETRY_AFTER_MS = 60_000;
38
+
39
+ /**
40
+ * Reemplaza cada `{name}` del path por su valor, en el orden de `pathParams`.
41
+ * Rechaza lo que cambiaría la ruta: vacío, null, undefined, `.` y `..` (igual que los SDK de Anthropic).
42
+ * Un `0` o un id con `/` pasan: el `/` se codifica y queda dentro del segmento.
43
+ */
44
+ function buildPath(spec: OperationSpec, pathValues: string[]): string {
45
+ let index = 0;
46
+ return spec.path.replace(/\{[^}]+\}/g, () => {
47
+ const name = spec.pathParams[index] ?? "id";
48
+ const value: unknown = pathValues[index++];
49
+ if (value === undefined || value === null || value === "") {
50
+ throw new LaburenArgumentError(`Path parameter "${name}" must not be empty.`);
51
+ }
52
+ const text = String(value);
53
+ if (text === "." || text === "..") {
54
+ throw new LaburenArgumentError(
55
+ `Path parameter "${name}" can't be "${text}": it would change the request path.`,
56
+ );
57
+ }
58
+ return encodeURIComponent(text);
59
+ });
60
+ }
61
+
62
+ /** Arma el query string: salta los undefined y repite la clave por cada item de un array. */
63
+ function buildQuery(params: Record<string, unknown> | undefined): string {
64
+ if (!params) return "";
65
+ const search = new URLSearchParams();
66
+ for (const [key, value] of Object.entries(params)) {
67
+ if (value === undefined) continue;
68
+ const items = Array.isArray(value) ? value : [value];
69
+ for (const item of items) {
70
+ if (item === undefined) continue;
71
+ search.append(key, typeof item === "object" ? JSON.stringify(item) : String(item));
72
+ }
73
+ }
74
+ const text = search.toString();
75
+ return text ? `?${text}` : "";
76
+ }
77
+
78
+ /** Lee `retry-after` (segundos o fecha HTTP); devuelve null si no sirve o pasa de 60 s. */
79
+ function parseRetryAfter(headers: Headers): number | null {
80
+ const raw = headers.get("retry-after");
81
+ if (raw === null) return null;
82
+ const seconds = Number(raw);
83
+ const ms =
84
+ Number.isFinite(seconds) && raw.trim() !== "" ? seconds * 1000 : Date.parse(raw) - Date.now();
85
+ if (!Number.isFinite(ms) || ms < 0 || ms > MAX_RETRY_AFTER_MS) return null;
86
+ return ms;
87
+ }
88
+
89
+ /** Espera calculada: 0,5 s * 2^n con tope de 8 s, con un poco de azar para no sincronizar clientes. */
90
+ function backoffMs(retriesDone: number): number {
91
+ const base = Math.min(0.5 * 2 ** retriesDone, 8) * 1000;
92
+ return base * (1 - Math.random() * 0.25);
93
+ }
94
+
95
+ /** Espera `ms`; si el llamador corta antes, rechaza con `LaburenAbortError` (el motivo de su señal va en `cause`). */
96
+ function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
97
+ return new Promise((resolve, reject) => {
98
+ if (signal?.aborted) return reject(new LaburenAbortError({ cause: signal.reason }));
99
+ const onAbort = () => {
100
+ clearTimeout(timer);
101
+ reject(new LaburenAbortError({ cause: signal?.reason }));
102
+ };
103
+ const timer = setTimeout(() => {
104
+ signal?.removeEventListener("abort", onAbort);
105
+ resolve();
106
+ }, ms);
107
+ signal?.addEventListener("abort", onAbort, { once: true });
108
+ });
109
+ }
110
+
111
+ /** Parsea sin lanzar: devuelve `ok: false` si el texto no es JSON (por ejemplo, una página HTML de Cloudflare). */
112
+ export function parseJson(text: string): { ok: true; value: unknown } | { ok: false } {
113
+ try {
114
+ return { ok: true, value: JSON.parse(text) };
115
+ } catch {
116
+ return { ok: false };
117
+ }
118
+ }
119
+
120
+ /**
121
+ * Hace el pedido de la operación con la misma key, los mismos reintentos y el mismo timeout por intento
122
+ * para todas las operaciones. `onOk` recibe la respuesta 2xx dentro del intento (y de su timer): lo que
123
+ * lance se trata como cualquier falla del intento. Devuelve lo que devuelva `onOk`.
124
+ */
125
+ export async function sendWithRetries<T>(
126
+ config: PlatformConfig,
127
+ spec: OperationSpec,
128
+ pathValues: string[],
129
+ params: Record<string, unknown> | undefined,
130
+ options: RequestOptions | undefined,
131
+ onOk: (response: Response, controller: AbortController) => Promise<T>,
132
+ ): Promise<T> {
133
+ const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
134
+ const doFetch = config.fetch ?? fetch;
135
+ const timeoutMs = options?.timeout ?? spec.timeoutMs ?? config.timeout ?? DEFAULT_TIMEOUT_MS;
136
+ const maxRetries = options?.maxRetries ?? config.maxRetries ?? DEFAULT_MAX_RETRIES;
137
+ const organization = options?.organization ?? config.organization;
138
+ const callerSignal = options?.signal;
139
+ const isGet = spec.method === "GET";
140
+ // Una sola key por llamada: se repite igual en cada reintento.
141
+ const idempotencyKey = spec.idempotent
142
+ ? options?.idempotencyKey || crypto.randomUUID()
143
+ : undefined;
144
+ // idempotencyKey nunca es un texto vacío, así que si hay key, el header se manda y se puede reintentar.
145
+ const canRetry = isGet || idempotencyKey !== undefined;
146
+
147
+ const url = `${baseUrl}${buildPath(spec, pathValues)}${isGet ? buildQuery(params) : ""}`;
148
+ const body = !isGet && params !== undefined ? JSON.stringify(params) : undefined;
149
+
150
+ for (let attempt = 0; ; attempt++) {
151
+ // Si la función del token lanza, el error sale tal cual y no se reintenta.
152
+ const token = typeof config.token === "function" ? await config.token() : config.token;
153
+ if (!token) throw new LaburenArgumentError("The token must not be empty.");
154
+ const headers = new Headers({ authorization: `Bearer ${token}` });
155
+ if (organization) headers.set("x-laburen-organization", organization);
156
+ if (idempotencyKey !== undefined) headers.set("idempotency-key", idempotencyKey);
157
+ if (body !== undefined) headers.set("content-type", "application/json");
158
+
159
+ const controller = new AbortController();
160
+ let timedOut = false;
161
+ const onCallerAbort = () => controller.abort(callerSignal?.reason);
162
+ if (callerSignal?.aborted) controller.abort(callerSignal.reason);
163
+ callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
164
+ // El timer es de este intento (no del módulo) para poder controlarlo en los tests.
165
+ const timer = setTimeout(() => {
166
+ timedOut = true;
167
+ controller.abort();
168
+ }, timeoutMs);
169
+
170
+ let failure: Error;
171
+ let retryAfterMs: number | null = null;
172
+ try {
173
+ const response = await doFetch(url, {
174
+ method: spec.method,
175
+ headers,
176
+ body,
177
+ signal: controller.signal,
178
+ });
179
+
180
+ if (response.ok) return await onOk(response, controller);
181
+
182
+ const text = await response.text();
183
+ const parsed = text === "" ? { ok: true as const, value: undefined } : parseJson(text);
184
+ const apiError = apiErrorFromResponse(
185
+ response.status,
186
+ parsed.ok ? parsed.value : undefined,
187
+ response.headers,
188
+ );
189
+ const retryable =
190
+ apiError.shouldRetry ??
191
+ (response.status === 408 || response.status === 429 || response.status >= 500);
192
+ if (!canRetry || !retryable || attempt >= maxRetries) throw apiError;
193
+ retryAfterMs = parseRetryAfter(response.headers);
194
+ } catch (error) {
195
+ if (isLaburenApiError(error)) throw error;
196
+ if (callerSignal?.aborted) throw new LaburenAbortError({ cause: callerSignal.reason });
197
+ failure = timedOut
198
+ ? new LaburenTimeoutError(`The server did not respond within ${timeoutMs} ms.`, {
199
+ cause: error,
200
+ })
201
+ : new LaburenConnectionError("Could not connect to the Laburen API.", {
202
+ cause: error,
203
+ });
204
+ if (!canRetry || attempt >= maxRetries) throw failure;
205
+ } finally {
206
+ clearTimeout(timer);
207
+ callerSignal?.removeEventListener("abort", onCallerAbort);
208
+ }
209
+
210
+ await sleep(retryAfterMs ?? backoffMs(attempt), callerSignal);
211
+ }
212
+ }
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Parser SSE propio, sin dependencias (reglas de `eventsource-parser` 3.0.6).
3
+ * Recibe el body de una respuesta y da el `data` de cada evento; los campos `event`, `id` y `retry` se ignoran.
4
+ * Termina en `data: [DONE]` o al cerrarse el body. Si el body se cierra sin la línea en blanco final,
5
+ * el evento pendiente se descarta, igual que `eventsource-parser`.
6
+ */
7
+ export async function* parseSse(
8
+ body: ReadableStream<Uint8Array>,
9
+ onBytes?: () => void,
10
+ ): AsyncIterable<string> {
11
+ const reader = body.getReader();
12
+ const decoder = new TextDecoder("utf-8");
13
+ let pending = "";
14
+ let data = "";
15
+
16
+ try {
17
+ while (true) {
18
+ const { done, value } = await reader.read();
19
+ if (done) return;
20
+ onBytes?.();
21
+
22
+ // `TextDecoder("utf-8")` saca solo el BOM del principio (ignoreBOM es false por defecto).
23
+ const text = decoder.decode(value, { stream: true });
24
+ const { lines, rest } = splitLines(pending + text);
25
+ pending = rest;
26
+
27
+ for (const line of lines) {
28
+ if (line === "") {
29
+ const event = data.endsWith("\n") ? data.slice(0, -1) : data;
30
+ const hasData = data.length > 0;
31
+ data = "";
32
+ if (!hasData) continue;
33
+ if (event === "[DONE]") return;
34
+ yield event;
35
+ } else if (line.startsWith(":")) {
36
+ // comentario (`: ping`)
37
+ } else {
38
+ const separator = line.indexOf(":");
39
+ const field = separator === -1 ? line : line.slice(0, separator);
40
+ if (field !== "data") continue;
41
+ const value = separator === -1 ? "" : line.slice(separator + 1);
42
+ data += `${value.startsWith(" ") ? value.slice(1) : value}\n`;
43
+ }
44
+ }
45
+ }
46
+ } finally {
47
+ await reader.cancel().catch(() => {});
48
+ }
49
+ }
50
+
51
+ /** Parte por CR, LF o CRLF; un CR al final queda en `rest` porque puede ser la mitad de un CRLF. */
52
+ function splitLines(text: string): { lines: string[]; rest: string } {
53
+ const lines: string[] = [];
54
+ let start = 0;
55
+ for (let i = 0; i < text.length; i++) {
56
+ const char = text[i];
57
+ if (char === "\n") {
58
+ lines.push(text.slice(start, i));
59
+ start = i + 1;
60
+ } else if (char === "\r") {
61
+ if (i === text.length - 1) break;
62
+ lines.push(text.slice(start, i));
63
+ start = text[i + 1] === "\n" ? i + 2 : i + 1;
64
+ if (text[i + 1] === "\n") i++;
65
+ }
66
+ }
67
+ return { lines, rest: text.slice(start) };
68
+ }