@mappa-ai/mappa-node 1.2.1 → 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>>;
   /**
@@ -260,6 +303,18 @@ type ReportOutputEntry<OutputType extends ReportOutputType, Template extends Rep
 };
 type ReportOutputForType<OutputType extends ReportOutputType> = ReportOutputEntry<OutputType, "sales_playbook"> | ReportOutputEntry<OutputType, "general_report"> | ReportOutputEntry<OutputType, "hiring_report"> | ReportOutputEntry<OutputType, "profile_alignment">;
 type ReportOutput = ReportOutputForType<"markdown"> | ReportOutputForType<"json"> | ReportOutputForType<"pdf"> | ReportOutputForType<"url">;
+/**
+ * Report output configuration constrained to a specific output type.
+ * When T is a specific literal like "markdown", only markdown output configs are allowed.
+ * When T is the full union (ReportOutputType), all output configs are allowed.
+ *
+ * @example
+ * ```typescript
+ * type MarkdownOutput = ReportOutputFor<"markdown">; // Only markdown configs
+ * type AnyOutput = ReportOutputFor<ReportOutputType>; // All configs (same as ReportOutput)
+ * ```
+ */
+type ReportOutputFor<T extends ReportOutputType> = T extends "markdown" ? ReportOutputForType<"markdown"> : T extends "json" ? ReportOutputForType<"json"> : T extends "pdf" ? ReportOutputForType<"pdf"> : T extends "url" ? ReportOutputForType<"url"> : ReportOutput;
 type TargetStrategy = "dominant" | "timerange" | "entity_id" | "magic_hint";
 type TargetOnMiss = "fallback_dominant" | "error";
 type TargetTimeRange = {
@@ -378,7 +433,7 @@ type WebhookConfig = {
   url: string;
   headers?: Record<string, string>;
 };
-type ReportCreateJobRequest = {
+type ReportCreateJobRequest<T extends ReportOutputType = ReportOutputType> = {
   subject?: Subject;
   /**
    * Reference to already-uploaded media.
@@ -387,7 +442,7 @@ type ReportCreateJobRequest = {
    * use helper methods like `reports.createJobFromUrl()` / `reports.createJobFromFile()`.
    */
   media: MediaIdRef;
-  output: ReportOutput;
+  output: ReportOutputFor<T>;
   /**
    * Select the target entity for analysis.
    *
@@ -468,13 +523,25 @@ type UrlReport = ReportBase & {
   reportUrl: string;
 };
 type Report = MarkdownReport | JsonReport | PdfReport | UrlReport;
-type ReportJobReceipt = {
+/**
+ * Maps an output type to its corresponding report type.
+ * Used for type-safe inference in generate methods.
+ *
+ * @example
+ * ```typescript
+ * type R = ReportForOutputType<"markdown">; // MarkdownReport
+ * type R = ReportForOutputType<"json">;     // JsonReport
+ * type R = ReportForOutputType<ReportOutputType>; // Report (union)
+ * ```
+ */
+type ReportForOutputType<T extends ReportOutputType> = T extends "markdown" ? MarkdownReport : T extends "json" ? JsonReport : T extends "pdf" ? PdfReport : T extends "url" ? UrlReport : Report;
+type ReportJobReceipt<T extends ReportOutputType = ReportOutputType> = {
   jobId: string;
   status: "queued" | "running";
   stage?: JobStage;
   estimatedWaitSec?: number;
   requestId?: string;
-  handle?: ReportRunHandle;
+  handle?: ReportRunHandle<T>;
 };
 type FeedbackReceipt = {
   id: string;
@@ -594,16 +661,16 @@ type WaitOptions = {
    */
   signal?: AbortSignal;
 };
-type ReportRunHandle = {
+type ReportRunHandle<T extends ReportOutputType = ReportOutputType> = {
   jobId: string;
   stream(opts?: {
     signal?: AbortSignal;
     onEvent?: (e: JobEvent) => void;
   }): AsyncIterable<JobEvent>;
-  wait(opts?: WaitOptions): Promise<Report>;
+  wait(opts?: WaitOptions): Promise<ReportForOutputType<T>>;
   cancel(): Promise<Job>;
   job(): Promise<Job>;
-  report(): Promise<Report | null>;
+  report(): Promise<ReportForOutputType<T> | null>;
 };
 /**
  * Type guard for MarkdownReport.
@@ -1102,7 +1169,7 @@ declare class JobsResource {
  * - `signal` (from {@link UploadRequest}) is applied to the upload request.
  *   Job creation only runs after a successful upload.
  */
-type ReportCreateJobFromFileRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & Omit<UploadRequest, "filename"> & {
+type ReportCreateJobFromFileRequest<T extends ReportOutputType = ReportOutputType> = Omit<ReportCreateJobRequest<T>, "media" | "idempotencyKey" | "requestId"> & Omit<UploadRequest, "filename"> & {
   /**
    * Optional filename to attach to the upload.
    *
@@ -1130,7 +1197,7 @@ type ReportCreateJobFromFileRequest = Omit<ReportCreateJobRequest, "media" | "id
  * - `idempotencyKey` applies to the *whole* download + upload + create-job sequence.
  * - `requestId` is forwarded to both upload and job creation calls.
  */
-type ReportCreateJobFromUrlRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & {
+type ReportCreateJobFromUrlRequest<T extends ReportOutputType = ReportOutputType> = Omit<ReportCreateJobRequest<T>, "media" | "idempotencyKey" | "requestId"> & {
   url: string;
   contentType?: string;
   filename?: string;
@@ -1176,14 +1243,14 @@ declare class ReportsResource {
    * - wait for completion and fetch the final report
    * - cancel the job, or fetch job/report metadata
    */
-  createJob(req: ReportCreateJobRequest): Promise<ReportJobReceipt>;
+  createJob<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobRequest<T>): Promise<ReportJobReceipt<T>>;
   /**
    * Upload a file and create a report job in one call.
    *
    * Keeps `createJob()` strict about `media: { mediaId }` while offering a
    * convenient helper when you start from raw bytes.
    */
-  createJobFromFile(req: ReportCreateJobFromFileRequest): Promise<ReportJobReceipt>;
+  createJobFromFile<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromFileRequest<T>): Promise<ReportJobReceipt<T>>;
   /**
    * Download a file from a URL, upload it, and create a report job.
    *
@@ -1200,7 +1267,7 @@ declare class ReportsResource {
    * - Only allows `http:` and `https:` URLs.
    * - Requires a resolvable `contentType` (from `req.contentType` or response header).
    */
-  createJobFromUrl(req: ReportCreateJobFromUrlRequest): Promise<ReportJobReceipt>;
+  createJobFromUrl<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromUrlRequest<T>): Promise<ReportJobReceipt<T>>;
   get(reportId: string, opts?: {
     requestId?: string;
     signal?: AbortSignal;
@@ -1213,24 +1280,24 @@ declare class ReportsResource {
    * Convenience wrapper: createJob + wait + get
    * Use for scripts; for production prefer createJob + webhooks/stream.
    */
-  generate(req: ReportCreateJobRequest, opts?: {
+  generate<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobRequest<T>, opts?: {
     wait?: WaitOptions;
-  }): Promise<Report>;
+  }): Promise<ReportForOutputType<T>>;
   /**
    * Convenience wrapper: createJobFromFile + wait + get.
    * Use for scripts; for production prefer createJobFromFile + webhooks/stream.
    */
-  generateFromFile(req: ReportCreateJobFromFileRequest, opts?: {
+  generateFromFile<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromFileRequest<T>, opts?: {
     wait?: WaitOptions;
-  }): Promise<Report>;
+  }): Promise<ReportForOutputType<T>>;
   /**
    * Convenience wrapper: createJobFromUrl + wait + get.
    * Use for scripts; for production prefer createJobFromUrl + webhooks/stream.
    */
-  generateFromUrl(req: ReportCreateJobFromUrlRequest, opts?: {
+  generateFromUrl<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromUrlRequest<T>, opts?: {
     wait?: WaitOptions;
-  }): Promise<Report>;
-  makeHandle(jobId: string): ReportRunHandle;
+  }): Promise<ReportForOutputType<T>>;
+  makeHandle<T extends ReportOutputType = ReportOutputType>(jobId: string): ReportRunHandle<T>;
   private defaultIdempotencyKey;
   private normalizeJobRequest;
 }
@@ -1349,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, ReportJobReceipt, ReportOutput, 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>>;
   /**
@@ -260,6 +303,18 @@ type ReportOutputEntry<OutputType extends ReportOutputType, Template extends Rep
 };
 type ReportOutputForType<OutputType extends ReportOutputType> = ReportOutputEntry<OutputType, "sales_playbook"> | ReportOutputEntry<OutputType, "general_report"> | ReportOutputEntry<OutputType, "hiring_report"> | ReportOutputEntry<OutputType, "profile_alignment">;
 type ReportOutput = ReportOutputForType<"markdown"> | ReportOutputForType<"json"> | ReportOutputForType<"pdf"> | ReportOutputForType<"url">;
+/**
+ * Report output configuration constrained to a specific output type.
+ * When T is a specific literal like "markdown", only markdown output configs are allowed.
+ * When T is the full union (ReportOutputType), all output configs are allowed.
+ *
+ * @example
+ * ```typescript
+ * type MarkdownOutput = ReportOutputFor<"markdown">; // Only markdown configs
+ * type AnyOutput = ReportOutputFor<ReportOutputType>; // All configs (same as ReportOutput)
+ * ```
+ */
+type ReportOutputFor<T extends ReportOutputType> = T extends "markdown" ? ReportOutputForType<"markdown"> : T extends "json" ? ReportOutputForType<"json"> : T extends "pdf" ? ReportOutputForType<"pdf"> : T extends "url" ? ReportOutputForType<"url"> : ReportOutput;
 type TargetStrategy = "dominant" | "timerange" | "entity_id" | "magic_hint";
 type TargetOnMiss = "fallback_dominant" | "error";
 type TargetTimeRange = {
@@ -378,7 +433,7 @@ type WebhookConfig = {
   url: string;
   headers?: Record<string, string>;
 };
-type ReportCreateJobRequest = {
+type ReportCreateJobRequest<T extends ReportOutputType = ReportOutputType> = {
   subject?: Subject;
   /**
    * Reference to already-uploaded media.
@@ -387,7 +442,7 @@ type ReportCreateJobRequest = {
    * use helper methods like `reports.createJobFromUrl()` / `reports.createJobFromFile()`.
    */
   media: MediaIdRef;
-  output: ReportOutput;
+  output: ReportOutputFor<T>;
   /**
    * Select the target entity for analysis.
    *
@@ -468,13 +523,25 @@ type UrlReport = ReportBase & {
   reportUrl: string;
 };
 type Report = MarkdownReport | JsonReport | PdfReport | UrlReport;
-type ReportJobReceipt = {
+/**
+ * Maps an output type to its corresponding report type.
+ * Used for type-safe inference in generate methods.
+ *
+ * @example
+ * ```typescript
+ * type R = ReportForOutputType<"markdown">; // MarkdownReport
+ * type R = ReportForOutputType<"json">;     // JsonReport
+ * type R = ReportForOutputType<ReportOutputType>; // Report (union)
+ * ```
+ */
+type ReportForOutputType<T extends ReportOutputType> = T extends "markdown" ? MarkdownReport : T extends "json" ? JsonReport : T extends "pdf" ? PdfReport : T extends "url" ? UrlReport : Report;
+type ReportJobReceipt<T extends ReportOutputType = ReportOutputType> = {
   jobId: string;
   status: "queued" | "running";
   stage?: JobStage;
   estimatedWaitSec?: number;
   requestId?: string;
-  handle?: ReportRunHandle;
+  handle?: ReportRunHandle<T>;
 };
 type FeedbackReceipt = {
   id: string;
@@ -594,16 +661,16 @@ type WaitOptions = {
    */
   signal?: AbortSignal;
 };
-type ReportRunHandle = {
+type ReportRunHandle<T extends ReportOutputType = ReportOutputType> = {
   jobId: string;
   stream(opts?: {
     signal?: AbortSignal;
     onEvent?: (e: JobEvent) => void;
   }): AsyncIterable<JobEvent>;
-  wait(opts?: WaitOptions): Promise<Report>;
+  wait(opts?: WaitOptions): Promise<ReportForOutputType<T>>;
   cancel(): Promise<Job>;
   job(): Promise<Job>;
-  report(): Promise<Report | null>;
+  report(): Promise<ReportForOutputType<T> | null>;
 };
 /**
  * Type guard for MarkdownReport.
@@ -1102,7 +1169,7 @@ declare class JobsResource {
  * - `signal` (from {@link UploadRequest}) is applied to the upload request.
  *   Job creation only runs after a successful upload.
  */
-type ReportCreateJobFromFileRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & Omit<UploadRequest, "filename"> & {
+type ReportCreateJobFromFileRequest<T extends ReportOutputType = ReportOutputType> = Omit<ReportCreateJobRequest<T>, "media" | "idempotencyKey" | "requestId"> & Omit<UploadRequest, "filename"> & {
   /**
    * Optional filename to attach to the upload.
    *
@@ -1130,7 +1197,7 @@ type ReportCreateJobFromFileRequest = Omit<ReportCreateJobRequest, "media" | "id
  * - `idempotencyKey` applies to the *whole* download + upload + create-job sequence.
  * - `requestId` is forwarded to both upload and job creation calls.
  */
-type ReportCreateJobFromUrlRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & {
+type ReportCreateJobFromUrlRequest<T extends ReportOutputType = ReportOutputType> = Omit<ReportCreateJobRequest<T>, "media" | "idempotencyKey" | "requestId"> & {
   url: string;
   contentType?: string;
   filename?: string;
@@ -1176,14 +1243,14 @@ declare class ReportsResource {
    * - wait for completion and fetch the final report
    * - cancel the job, or fetch job/report metadata
    */
-  createJob(req: ReportCreateJobRequest): Promise<ReportJobReceipt>;
+  createJob<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobRequest<T>): Promise<ReportJobReceipt<T>>;
   /**
    * Upload a file and create a report job in one call.
    *
    * Keeps `createJob()` strict about `media: { mediaId }` while offering a
    * convenient helper when you start from raw bytes.
    */
-  createJobFromFile(req: ReportCreateJobFromFileRequest): Promise<ReportJobReceipt>;
+  createJobFromFile<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromFileRequest<T>): Promise<ReportJobReceipt<T>>;
   /**
    * Download a file from a URL, upload it, and create a report job.
    *
@@ -1200,7 +1267,7 @@ declare class ReportsResource {
    * - Only allows `http:` and `https:` URLs.
    * - Requires a resolvable `contentType` (from `req.contentType` or response header).
    */
-  createJobFromUrl(req: ReportCreateJobFromUrlRequest): Promise<ReportJobReceipt>;
+  createJobFromUrl<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromUrlRequest<T>): Promise<ReportJobReceipt<T>>;
   get(reportId: string, opts?: {
     requestId?: string;
     signal?: AbortSignal;
@@ -1213,24 +1280,24 @@ declare class ReportsResource {
    * Convenience wrapper: createJob + wait + get
    * Use for scripts; for production prefer createJob + webhooks/stream.
    */
-  generate(req: ReportCreateJobRequest, opts?: {
+  generate<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobRequest<T>, opts?: {
     wait?: WaitOptions;
-  }): Promise<Report>;
+  }): Promise<ReportForOutputType<T>>;
   /**
    * Convenience wrapper: createJobFromFile + wait + get.
    * Use for scripts; for production prefer createJobFromFile + webhooks/stream.
    */
-  generateFromFile(req: ReportCreateJobFromFileRequest, opts?: {
+  generateFromFile<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromFileRequest<T>, opts?: {
     wait?: WaitOptions;
-  }): Promise<Report>;
+  }): Promise<ReportForOutputType<T>>;
   /**
    * Convenience wrapper: createJobFromUrl + wait + get.
    * Use for scripts; for production prefer createJobFromUrl + webhooks/stream.
    */
-  generateFromUrl(req: ReportCreateJobFromUrlRequest, opts?: {
+  generateFromUrl<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromUrlRequest<T>, opts?: {
     wait?: WaitOptions;
-  }): Promise<Report>;
-  makeHandle(jobId: string): ReportRunHandle;
+  }): Promise<ReportForOutputType<T>>;
+  makeHandle<T extends ReportOutputType = ReportOutputType>(jobId: string): ReportRunHandle<T>;
   private defaultIdempotencyKey;
   private normalizeJobRequest;
 }
@@ -1349,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, ReportJobReceipt, ReportOutput, 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