@mappa-ai/mappa-node 1.2.2 → 1.2.3

package/dist/index.d.cts

@@ -119,6 +119,44 @@ declare class JobCanceledError extends MappaError {
   });
   toString(): string;
 }
+/**
+ * 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)
+ *   }
+ * }
+ * ```
+ */
+declare class StreamError extends MappaError {
+  name: string;
+  jobId?: string;
+  lastEventId?: string;
+  url?: string;
+  retryCount: number;
+  constructor(message: string, opts: {
+    jobId?: string;
+    lastEventId?: string;
+    url?: string;
+    retryCount: number;
+    requestId?: string;
+    cause?: unknown;
+  });
+  toString(): string;
+}
 //#endregion
 //#region src/resources/transport.d.ts
 /**
@@ -152,6 +190,8 @@ type Telemetry = {
     url: string;
     requestId?: string;
     error: unknown;
+    /** Additional context for SSE streaming errors. */
+    context?: Record<string, unknown>;
   }) => void;
 };
 type TransportOptions = {
@@ -190,6 +230,9 @@ declare class Transport {
    *
    * 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.
    */
   streamSSE<T>(path: string, opts?: SSEStreamOptions): AsyncGenerator<SSEEvent<T>>;
   /**
@@ -1373,6 +1416,26 @@ declare function isMappaError(err: unknown): err is MappaError;
  * ```
  */
 declare function isInsufficientCreditsError(err: unknown): err is 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}`);
+ *   }
+ * }
+ * ```
+ */
+declare function isStreamError(err: unknown): err is StreamError;
 //#endregion
-export { ApiError, AuthError, CreditBalance, CreditTransaction, CreditTransactionType, CreditUsage, CursorPage, CursorPaginationParams, Entity, EntityTagsResult, FeedbackReceipt, FileDeleteReceipt, InsufficientCreditsError, Job, JobCanceledError, JobCreditReservation, JobEvent, JobFailedError, JobStage, JobStatus, JsonReport, JsonValue, ListEntitiesOptions, ListEntitiesResponse, Mappa, MappaError, MarkdownReport, MediaFile, MediaIdRef, MediaObject, MediaProcessingStatus, MediaRef, MediaRetention, OffsetPage, OffsetPaginationParams, PdfReport, RateLimitError, Report, ReportBase, ReportCreateJobRequest, ReportForOutputType, ReportJobReceipt, ReportOutput, ReportOutputFor, ReportOutputType, ReportRunHandle, ReportTemplateId, ReportTemplateParamsMap, RetentionLockResult, Subject, TargetDominant, TargetEntityId, TargetFor, TargetMagicHint, TargetOnMiss, TargetSelector, TargetStrategy, TargetStrategyMap, TargetTimeRange, TargetTimeRangeStrategy, UrlReport, Usage, ValidationError, WaitOptions, WebhookConfig, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isUrlReport };
+export { ApiError, AuthError, CreditBalance, CreditTransaction, CreditTransactionType, CreditUsage, CursorPage, CursorPaginationParams, Entity, EntityTagsResult, FeedbackReceipt, FileDeleteReceipt, InsufficientCreditsError, Job, JobCanceledError, JobCreditReservation, JobEvent, JobFailedError, JobStage, JobStatus, JsonReport, JsonValue, ListEntitiesOptions, ListEntitiesResponse, Mappa, MappaError, MarkdownReport, MediaFile, MediaIdRef, MediaObject, MediaProcessingStatus, MediaRef, MediaRetention, OffsetPage, OffsetPaginationParams, PdfReport, RateLimitError, Report, ReportBase, ReportCreateJobRequest, ReportForOutputType, ReportJobReceipt, ReportOutput, ReportOutputFor, ReportOutputType, ReportRunHandle, ReportTemplateId, ReportTemplateParamsMap, RetentionLockResult, StreamError, Subject, TargetDominant, TargetEntityId, TargetFor, TargetMagicHint, TargetOnMiss, TargetSelector, TargetStrategy, TargetStrategyMap, TargetTimeRange, TargetTimeRangeStrategy, UrlReport, Usage, ValidationError, WaitOptions, WebhookConfig, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isStreamError, isUrlReport };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -119,6 +119,44 @@ declare class JobCanceledError extends MappaError {
   });
   toString(): string;
 }
+/**
+ * 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)
+ *   }
+ * }
+ * ```
+ */
+declare class StreamError extends MappaError {
+  name: string;
+  jobId?: string;
+  lastEventId?: string;
+  url?: string;
+  retryCount: number;
+  constructor(message: string, opts: {
+    jobId?: string;
+    lastEventId?: string;
+    url?: string;
+    retryCount: number;
+    requestId?: string;
+    cause?: unknown;
+  });
+  toString(): string;
+}
 //#endregion
 //#region src/resources/transport.d.ts
 /**
@@ -152,6 +190,8 @@ type Telemetry = {
     url: string;
     requestId?: string;
     error: unknown;
+    /** Additional context for SSE streaming errors. */
+    context?: Record<string, unknown>;
   }) => void;
 };
 type TransportOptions = {
@@ -190,6 +230,9 @@ declare class Transport {
    *
    * 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.
    */
   streamSSE<T>(path: string, opts?: SSEStreamOptions): AsyncGenerator<SSEEvent<T>>;
   /**
@@ -1373,6 +1416,26 @@ declare function isMappaError(err: unknown): err is MappaError;
  * ```
  */
 declare function isInsufficientCreditsError(err: unknown): err is 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}`);
+ *   }
+ * }
+ * ```
+ */
+declare function isStreamError(err: unknown): err is StreamError;
 //#endregion
-export { ApiError, AuthError, CreditBalance, CreditTransaction, CreditTransactionType, CreditUsage, CursorPage, CursorPaginationParams, Entity, EntityTagsResult, FeedbackReceipt, FileDeleteReceipt, InsufficientCreditsError, Job, JobCanceledError, JobCreditReservation, JobEvent, JobFailedError, JobStage, JobStatus, JsonReport, JsonValue, ListEntitiesOptions, ListEntitiesResponse, Mappa, MappaError, MarkdownReport, MediaFile, MediaIdRef, MediaObject, MediaProcessingStatus, MediaRef, MediaRetention, OffsetPage, OffsetPaginationParams, PdfReport, RateLimitError, Report, ReportBase, ReportCreateJobRequest, ReportForOutputType, ReportJobReceipt, ReportOutput, ReportOutputFor, ReportOutputType, ReportRunHandle, ReportTemplateId, ReportTemplateParamsMap, RetentionLockResult, Subject, TargetDominant, TargetEntityId, TargetFor, TargetMagicHint, TargetOnMiss, TargetSelector, TargetStrategy, TargetStrategyMap, TargetTimeRange, TargetTimeRangeStrategy, UrlReport, Usage, ValidationError, WaitOptions, WebhookConfig, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isUrlReport };
+export { ApiError, AuthError, CreditBalance, CreditTransaction, CreditTransactionType, CreditUsage, CursorPage, CursorPaginationParams, Entity, EntityTagsResult, FeedbackReceipt, FileDeleteReceipt, InsufficientCreditsError, Job, JobCanceledError, JobCreditReservation, JobEvent, JobFailedError, JobStage, JobStatus, JsonReport, JsonValue, ListEntitiesOptions, ListEntitiesResponse, Mappa, MappaError, MarkdownReport, MediaFile, MediaIdRef, MediaObject, MediaProcessingStatus, MediaRef, MediaRetention, OffsetPage, OffsetPaginationParams, PdfReport, RateLimitError, Report, ReportBase, ReportCreateJobRequest, ReportForOutputType, ReportJobReceipt, ReportOutput, ReportOutputFor, ReportOutputType, ReportRunHandle, ReportTemplateId, ReportTemplateParamsMap, RetentionLockResult, StreamError, Subject, TargetDominant, TargetEntityId, TargetFor, TargetMagicHint, TargetOnMiss, TargetSelector, TargetStrategy, TargetStrategyMap, TargetTimeRange, TargetTimeRangeStrategy, UrlReport, Usage, ValidationError, WaitOptions, WebhookConfig, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isStreamError, isUrlReport };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -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.
@@ -1711,7 +1808,29 @@ 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
-export { ApiError, AuthError, InsufficientCreditsError, JobCanceledError, JobFailedError, Mappa, MappaError, RateLimitError, ValidationError, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isUrlReport };
+export { ApiError, AuthError, InsufficientCreditsError, JobCanceledError, JobFailedError, Mappa, MappaError, RateLimitError, StreamError, ValidationError, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isStreamError, isUrlReport };
 //# sourceMappingURL=index.mjs.map