@mappa-ai/mappa-node 1.2.2 → 1.2.4

package/dist/index.cjs

@@ -170,6 +170,54 @@ var JobCanceledError = class extends MappaError {
 		return lines.join("\n");
 	}
 };
+/**
+* Error thrown when SSE streaming fails after all retries.
+*
+* Includes recovery metadata to allow callers to resume or retry:
+* - `jobId`: The job being streamed (when known)
+* - `lastEventId`: Last successfully received event ID for resumption
+* - `url`: The stream URL that failed
+* - `retryCount`: Number of retries attempted
+*
+* @example
+* ```typescript
+* try {
+*   for await (const event of mappa.jobs.stream(jobId)) { ... }
+* } catch (err) {
+*   if (err instanceof StreamError) {
+*     console.log(`Stream failed for job ${err.jobId}`);
+*     console.log(`Last event ID: ${err.lastEventId}`);
+*     // Can retry with: mappa.jobs.stream(err.jobId)
+*   }
+* }
+* ```
+*/
+var StreamError = class extends MappaError {
+	name = "StreamError";
+	jobId;
+	lastEventId;
+	url;
+	retryCount;
+	constructor(message, opts) {
+		super(message, {
+			requestId: opts.requestId,
+			cause: opts.cause
+		});
+		this.jobId = opts.jobId;
+		this.lastEventId = opts.lastEventId;
+		this.url = opts.url;
+		this.retryCount = opts.retryCount;
+	}
+	toString() {
+		const lines = [`${this.name}: ${this.message}`];
+		if (this.jobId) lines.push(`  Job ID: ${this.jobId}`);
+		if (this.lastEventId) lines.push(`  Last Event ID: ${this.lastEventId}`);
+		if (this.url) lines.push(`  URL: ${this.url}`);
+		lines.push(`  Retry Count: ${this.retryCount}`);
+		if (this.requestId) lines.push(`  Request ID: ${this.requestId}`);
+		return lines.join("\n");
+	}
+};
 
 //#endregion
 //#region src/resources/credits.ts
@@ -885,10 +933,19 @@ var JobsResource = class {
 		} catch (error) {
 			if (opts?.signal?.aborted) throw error;
 			retries++;
-			if (retries >= maxRetries) throw error;
+			if (retries >= maxRetries) throw new StreamError(`Stream connection failed for job ${jobId} after ${maxRetries} retries`, {
+				jobId,
+				lastEventId,
+				retryCount: retries,
+				cause: error
+			});
 			await this.backoff(retries);
 		}
-		throw new MappaError(`Failed to get status for job ${jobId} after ${maxRetries} retries`);
+		throw new StreamError(`Failed to get status for job ${jobId} after ${maxRetries} retries`, {
+			jobId,
+			lastEventId,
+			retryCount: maxRetries
+		});
 	}
 	/**
 	* Map an SSE event to a JobEvent.
@@ -1270,6 +1327,25 @@ function shouldRetry(opts, err) {
 	if (err instanceof TypeError) return { retry: true };
 	return { retry: false };
 }
+/**
+* Checks if an error is a network-level failure that's safe to retry.
+* Includes socket failures, DNS errors, and fetch TypeErrors.
+*/
+function isNetworkError(err) {
+	if (err instanceof TypeError) return true;
+	if (err && typeof err === "object") {
+		const code = err.code;
+		if (typeof code === "string") return [
+			"FailedToOpenSocket",
+			"ECONNREFUSED",
+			"ECONNRESET",
+			"ETIMEDOUT",
+			"ENOTFOUND",
+			"EAI_AGAIN"
+		].includes(code);
+	}
+	return false;
+}
 var Transport = class {
 	fetchImpl;
 	constructor(opts) {
@@ -1281,10 +1357,14 @@ var Transport = class {
 	*
 	* Uses native `fetch` with streaming response body (not browser-only `EventSource`).
 	* Parses SSE format manually from the `ReadableStream`.
+	*
+	* Automatically retries on network failures (socket errors, DNS failures, etc.)
+	* up to `maxRetries` times with exponential backoff.
 	*/
 	async *streamSSE(path, opts) {
 		const url = buildUrl(this.opts.baseUrl, path);
 		const requestId = randomId("req");
+		const maxRetries = Math.max(0, this.opts.maxRetries);
 		const headers = {
 			Accept: "text/event-stream",
 			"Cache-Control": "no-cache",
@@ -1294,57 +1374,74 @@ var Transport = class {
 			...this.opts.defaultHeaders ?? {}
 		};
 		if (opts?.lastEventId) headers["Last-Event-ID"] = opts.lastEventId;
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(makeAbortError()), this.opts.timeoutMs);
-		if (hasAbortSignal(opts?.signal)) {
-			const signal = opts?.signal;
-			if (signal?.aborted) {
-				clearTimeout(timeout);
-				throw makeAbortError();
-			}
-			signal?.addEventListener("abort", () => controller.abort(makeAbortError()), { once: true });
-		}
-		this.opts.telemetry?.onRequest?.({
-			method: "GET",
-			url,
-			requestId
-		});
 		let res;
-		try {
-			res = await this.fetchImpl(url, {
+		let lastError;
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(makeAbortError()), this.opts.timeoutMs);
+			if (hasAbortSignal(opts?.signal)) {
+				const signal = opts?.signal;
+				if (signal?.aborted) {
+					clearTimeout(timeout);
+					throw makeAbortError();
+				}
+				signal?.addEventListener("abort", () => controller.abort(makeAbortError()), { once: true });
+			}
+			this.opts.telemetry?.onRequest?.({
 				method: "GET",
-				headers,
-				signal: controller.signal
-			});
-		} catch (err) {
-			clearTimeout(timeout);
-			this.opts.telemetry?.onError?.({
-				url,
-				requestId,
-				error: err
-			});
-			throw err;
-		}
-		if (!res.ok) {
-			clearTimeout(timeout);
-			const { parsed } = await readBody(res);
-			const apiErr = coerceApiError(res, parsed);
-			this.opts.telemetry?.onError?.({
 				url,
-				requestId,
-				error: apiErr
+				requestId
 			});
-			throw apiErr;
-		}
-		if (!res.body) {
-			clearTimeout(timeout);
-			throw new MappaError("SSE response has no body");
-		}
-		try {
-			yield* this.parseSSEStream(res.body);
-		} finally {
-			clearTimeout(timeout);
+			try {
+				res = await this.fetchImpl(url, {
+					method: "GET",
+					headers,
+					signal: controller.signal
+				});
+				clearTimeout(timeout);
+				if (!res.ok) {
+					const { parsed } = await readBody(res);
+					const apiErr = coerceApiError(res, parsed);
+					this.opts.telemetry?.onError?.({
+						url,
+						requestId,
+						error: apiErr,
+						context: {
+							attempt,
+							lastEventId: opts?.lastEventId
+						}
+					});
+					if (res.status >= 500 && res.status <= 599 && attempt < maxRetries) {
+						const delay = jitter(backoffMs(attempt + 1, 500, 4e3));
+						await new Promise((r) => setTimeout(r, delay));
+						continue;
+					}
+					throw apiErr;
+				}
+				break;
+			} catch (err) {
+				clearTimeout(timeout);
+				lastError = err;
+				this.opts.telemetry?.onError?.({
+					url,
+					requestId,
+					error: err,
+					context: {
+						attempt,
+						lastEventId: opts?.lastEventId
+					}
+				});
+				if (isNetworkError(err) && attempt < maxRetries) {
+					const delay = jitter(backoffMs(attempt + 1, 500, 4e3));
+					await new Promise((r) => setTimeout(r, delay));
+					continue;
+				}
+				throw err;
+			}
 		}
+		if (!res) throw lastError;
+		if (!res.body) throw new MappaError("SSE response has no body");
+		yield* this.parseSSEStream(res.body);
 	}
 	/**
 	* Parse SSE events from a ReadableStream.
@@ -1517,7 +1614,7 @@ function isObject(v) {
 }
 /**
 * Async signature verification using WebCrypto (works in modern Node and browsers).
-* Signature scheme placeholder:
+* Signature scheme:
 *   headers["mappa-signature"] = "t=1700000000,v1=<hex_hmac_sha256>"
 * Signed payload: `${t}.${rawBody}`
 */
@@ -1535,20 +1632,24 @@ var WebhooksResource = class {
 		if (!timingSafeEqualHex(await hmacHex(params.secret, signed), parts.v1)) throw new Error("Invalid signature");
 		return { ok: true };
 	}
+	/**
+	* Parse and validate a webhook event payload.
+	*
+	* @param payload - Raw JSON string from the webhook request body
+	* @returns Parsed and validated webhook event
+	* @throws Error if payload is invalid or missing required fields
+	*/
 	parseEvent(payload) {
 		const raw = JSON.parse(payload);
 		if (!isObject(raw)) throw new Error("Invalid webhook payload: not an object");
 		const obj = raw;
-		const id = obj.id;
 		const type = obj.type;
-		const createdAt = obj.createdAt;
-		if (typeof id !== "string") throw new Error("Invalid webhook payload: id must be a string");
+		const timestamp = obj.timestamp;
 		if (typeof type !== "string") throw new Error("Invalid webhook payload: type must be a string");
-		if (typeof createdAt !== "string") throw new Error("Invalid webhook payload: createdAt must be a string");
+		if (typeof timestamp !== "string") throw new Error("Invalid webhook payload: timestamp must be a string");
 		return {
-			id,
 			type,
-			createdAt,
+			timestamp,
 			data: "data" in obj ? obj.data : void 0
 		};
 	}
@@ -1711,6 +1812,28 @@ function isMappaError(err) {
 function isInsufficientCreditsError(err) {
 	return err instanceof InsufficientCreditsError;
 }
+/**
+* Type guard for stream connection errors.
+*
+* Use this to detect streaming failures and access recovery metadata
+* like `jobId`, `lastEventId`, and `retryCount`.
+*
+* @example
+* ```typescript
+* try {
+*   await mappa.reports.generate({ ... });
+* } catch (err) {
+*   if (isStreamError(err)) {
+*     console.log(`Stream failed for job ${err.jobId}`);
+*     console.log(`Last event ID: ${err.lastEventId}`);
+*     console.log(`Retries attempted: ${err.retryCount}`);
+*   }
+* }
+* ```
+*/
+function isStreamError(err) {
+	return err instanceof StreamError;
+}
 
 //#endregion
 exports.ApiError = ApiError;
@@ -1721,6 +1844,7 @@ exports.JobFailedError = JobFailedError;
 exports.Mappa = Mappa;
 exports.MappaError = MappaError;
 exports.RateLimitError = RateLimitError;
+exports.StreamError = StreamError;
 exports.ValidationError = ValidationError;
 exports.hasEntity = hasEntity;
 exports.isInsufficientCreditsError = isInsufficientCreditsError;
@@ -1728,5 +1852,6 @@ exports.isJsonReport = isJsonReport;
 exports.isMappaError = isMappaError;
 exports.isMarkdownReport = isMarkdownReport;
 exports.isPdfReport = isPdfReport;
+exports.isStreamError = isStreamError;
 exports.isUrlReport = isUrlReport;
 //# sourceMappingURL=index.cjs.map