@mappa-ai/mappa-node 1.2.0 → 1.2.2

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,6 +117,7 @@ declare class JobCanceledError extends MappaError {
     requestId?: string;
     cause?: unknown;
   });
+  toString(): string;
 }
 //#endregion
 //#region src/resources/transport.d.ts
@@ -215,6 +260,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 = {
@@ -333,7 +390,7 @@ type WebhookConfig = {
   url: string;
   headers?: Record<string, string>;
 };
-type ReportCreateJobRequest = {
+type ReportCreateJobRequest<T extends ReportOutputType = ReportOutputType> = {
   subject?: Subject;
   /**
    * Reference to already-uploaded media.
@@ -342,11 +399,11 @@ type ReportCreateJobRequest = {
    * use helper methods like `reports.createJobFromUrl()` / `reports.createJobFromFile()`.
    */
   media: MediaIdRef;
-  output: ReportOutput;
+  output: ReportOutputFor<T>;
   /**
    * 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?: {
@@ -371,6 +428,7 @@ type ReportCreateJobRequest = {
 type ReportBase = {
   id: string;
   createdAt: string;
+  jobId?: string;
   subject?: Subject;
   media: {
     url?: string;
@@ -387,12 +445,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;
@@ -402,7 +462,7 @@ type JsonReport = ReportBase & {
 type PdfReport = ReportBase & {
   output: {
     type: "pdf";
-    template: string;
+    template: ReportTemplateId;
   };
   markdown: string;
   pdfUrl: string;
@@ -410,23 +470,35 @@ 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;
   }>;
   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;
@@ -546,16 +618,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.
@@ -1054,7 +1126,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.
    *
@@ -1082,7 +1154,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;
@@ -1119,6 +1191,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.
    *
@@ -1127,14 +1200,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.
    *
@@ -1151,7 +1224,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;
@@ -1164,24 +1237,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;
 }
@@ -1285,5 +1358,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, 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 };
+//# sourceMappingURL=index.d.mts.map