@mappa-ai/mappa-node 1.1.1 → 1.2.1

package/dist/index.d.mts

@@ -1,4 +1,9 @@
 //#region src/errors.d.ts
+/**
+ * Symbol for custom Node.js inspect formatting.
+ * Ensures errors display nicely in console.log, REPL, and debuggers.
+ */
+declare const customInspect: unique symbol;
 /**
  * Base error type for all SDK-raised errors.
  *
@@ -14,6 +19,8 @@ declare class MappaError extends Error {
     code?: string;
     cause?: unknown;
   });
+  toString(): string;
+  [customInspect](): string;
 }
 /**
  * Error returned when the API responds with a non-2xx status.
@@ -28,6 +35,7 @@ declare class ApiError extends MappaError {
     code?: string;
     details?: unknown;
   });
+  toString(): string;
 }
 /**
  * Error returned for HTTP 429 responses.
@@ -38,6 +46,7 @@ declare class ApiError extends MappaError {
 declare class RateLimitError extends ApiError {
   name: string;
   retryAfterMs?: number;
+  toString(): string;
 }
 /**
  * Error returned for authentication/authorization failures (typically 401/403).
@@ -51,6 +60,40 @@ declare class AuthError extends ApiError {
 declare class ValidationError extends ApiError {
   name: string;
 }
+/**
+ * Error returned when the account lacks sufficient credits (HTTP 402).
+ *
+ * Use {@link InsufficientCreditsError.required} and {@link InsufficientCreditsError.available}
+ * to inform users how many credits are needed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await mappa.reports.createJob({ ... });
+ * } catch (err) {
+ *   if (err instanceof InsufficientCreditsError) {
+ *     console.log(`Need ${err.required} credits, have ${err.available}`);
+ *   }
+ * }
+ * ```
+ */
+declare class InsufficientCreditsError extends ApiError {
+  name: string;
+  /** Credits required for the operation */
+  required: number;
+  /** Credits currently available */
+  available: number;
+  constructor(message: string, opts: {
+    status: number;
+    requestId?: string;
+    code?: string;
+    details?: {
+      required?: number;
+      available?: number;
+    };
+  });
+  toString(): string;
+}
 /**
  * Error thrown by polling helpers when a job reaches the "failed" terminal state.
  */
@@ -62,6 +105,7 @@ declare class JobFailedError extends MappaError {
     code?: string;
     cause?: unknown;
   });
+  toString(): string;
 }
 /**
  * Error thrown by polling helpers when a job reaches the "canceled" terminal state.
@@ -73,9 +117,25 @@ declare class JobCanceledError extends MappaError {
     requestId?: string;
     cause?: unknown;
   });
+  toString(): string;
 }
 //#endregion
 //#region src/resources/transport.d.ts
+/**
+ * Options for SSE streaming.
+ */
+type SSEStreamOptions = {
+  signal?: AbortSignal;
+  lastEventId?: string;
+};
+/**
+ * A parsed SSE event.
+ */
+type SSEEvent<T = unknown> = {
+  id?: string;
+  event: string;
+  data: T;
+};
 type Telemetry = {
   onRequest?: (ctx: {
     method: string;
@@ -125,6 +185,30 @@ declare class Transport {
   private readonly opts;
   private readonly fetchImpl;
   constructor(opts: TransportOptions);
+  /**
+   * Stream SSE events from a given path.
+   *
+   * Uses native `fetch` with streaming response body (not browser-only `EventSource`).
+   * Parses SSE format manually from the `ReadableStream`.
+   */
+  streamSSE<T>(path: string, opts?: SSEStreamOptions): AsyncGenerator<SSEEvent<T>>;
+  /**
+   * Parse SSE events from a ReadableStream.
+   *
+   * SSE format:
+   * ```
+   * id: <id>
+   * event: <type>
+   * data: <json>
+   *
+   * ```
+   * Each event is terminated by an empty line.
+   */
+  private parseSSEStream;
+  /**
+   * Parse a single SSE event from text.
+   */
+  private parseSSEEvent;
   request<T>(req: RequestOptions): Promise<TransportResponse<T>>;
 }
 //#endregion
@@ -307,7 +391,7 @@ type ReportCreateJobRequest = {
   /**
    * Select the target entity for analysis.
    *
-   * When omitted, the API defaults to the dominant speaker.
+   * @defaultValue `{ strategy: "dominant" }` - analyzes the dominant speaker
    */
   target?: TargetSelector;
   options?: {
@@ -332,6 +416,7 @@ type ReportCreateJobRequest = {
 type ReportBase = {
   id: string;
   createdAt: string;
+  jobId?: string;
   subject?: Subject;
   media: {
     url?: string;
@@ -348,12 +433,14 @@ type ReportBase = {
 type MarkdownReport = ReportBase & {
   output: {
     type: "markdown";
+    template: ReportTemplateId;
   };
   markdown: string;
 };
 type JsonReport = ReportBase & {
   output: {
     type: "json";
+    template: ReportTemplateId;
   };
   sections: Array<{
     section_title: string;
@@ -363,7 +450,7 @@ type JsonReport = ReportBase & {
 type PdfReport = ReportBase & {
   output: {
     type: "pdf";
-    template: string;
+    template: ReportTemplateId;
   };
   markdown: string;
   pdfUrl: string;
@@ -371,10 +458,10 @@ type PdfReport = ReportBase & {
 type UrlReport = ReportBase & {
   output: {
     type: "url";
-    template: string;
+    template: ReportTemplateId;
   };
-  markdown?: string;
-  sections?: Array<{
+  markdown: string;
+  sections: Array<{
     section_title: string;
     section_content: JsonValue;
   }>;
@@ -489,7 +576,7 @@ type CreditUsage = {
   modelVersion?: string;
 };
 /**
- * Options for long-polling job completion.
+ * Options for waiting on job completion.
  */
 type WaitOptions = {
   /**
@@ -498,18 +585,6 @@ type WaitOptions = {
    * @defaultValue 300000
    */
   timeoutMs?: number;
-  /**
-   * Initial polling interval.
-   *
-   * @defaultValue 1000
-   */
-  pollIntervalMs?: number;
-  /**
-   * Maximum polling interval used with exponential backoff.
-   *
-   * @defaultValue 10000
-   */
-  maxPollIntervalMs?: number;
   /**
    * Optional callback invoked on meaningful job state transitions.
    */
@@ -984,16 +1059,30 @@ declare class JobsResource {
     requestId?: string;
     signal?: AbortSignal;
   }): Promise<Job>;
+  /**
+   * Wait for a job to reach a terminal state.
+   *
+   * Uses SSE streaming internally for efficient real-time updates.
+   */
   wait(jobId: string, opts?: WaitOptions): Promise<Job>;
   /**
-   * Public stream API.
-   * If you add SSE later, keep this signature and switch implementation internally.
-   * For now, it yields events based on polling. Use `AbortSignal` to cancel streaming.
+   * Stream job events via SSE.
+   *
+   * Yields events as they arrive from the server. Use `AbortSignal` to cancel streaming.
+   * Automatically handles reconnection with `Last-Event-ID` for up to 3 retries.
    */
   stream(jobId: string, opts?: {
     signal?: AbortSignal;
     onEvent?: (e: JobEvent) => void;
   }): AsyncIterable<JobEvent>;
+  /**
+   * Map an SSE event to a JobEvent.
+   */
+  private mapSSEToJobEvent;
+  /**
+   * Exponential backoff with jitter for reconnection.
+   */
+  private backoff;
 }
 //#endregion
 //#region src/resources/reports.d.ts
@@ -1078,6 +1167,7 @@ declare class ReportsResource {
    *
    * Behavior:
    * - Validates {@link MediaIdRef} at runtime (must provide `{ mediaId }`).
+   * - Defaults to `{ strategy: "dominant" }` when `target` is omitted.
    * - Applies an idempotency key: uses `req.idempotencyKey` when provided; otherwise generates a best-effort default.
    * - Forwards `req.requestId` to the transport for end-to-end correlation.
    *
@@ -1244,5 +1334,21 @@ declare class Mappa {
  * Type guard for catching SDK errors.
  */
 declare function isMappaError(err: unknown): err is MappaError;
+/**
+ * Type guard for insufficient credits errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await mappa.reports.createJob({ ... });
+ * } catch (err) {
+ *   if (isInsufficientCreditsError(err)) {
+ *     console.log(`Need ${err.required} credits, have ${err.available}`);
+ *   }
+ * }
+ * ```
+ */
+declare function isInsufficientCreditsError(err: unknown): err is InsufficientCreditsError;
 //#endregion
-export { ApiError, AuthError, CreditBalance, CreditTransaction, CreditTransactionType, CreditUsage, CursorPage, CursorPaginationParams, Entity, EntityTagsResult, FeedbackReceipt, FileDeleteReceipt, 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, 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, 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 };
+//# sourceMappingURL=index.d.mts.map