@mappa-ai/mappa-node 1.2.1 → 1.2.2

package/dist/index.d.cts

@@ -260,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 = {
@@ -378,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.
@@ -387,7 +399,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 +480,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 +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.
@@ -1102,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.
    *
@@ -1130,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;
@@ -1176,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.
    *
@@ -1200,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;
@@ -1213,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;
 }
@@ -1350,5 +1374,5 @@ declare function isMappaError(err: unknown): err is MappaError;
  */
 declare function isInsufficientCreditsError(err: unknown): err is InsufficientCreditsError;
 //#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, 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.cts.map

package/dist/index.d.mts

@@ -260,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 = {
@@ -378,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.
@@ -387,7 +399,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 +480,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 +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.
@@ -1102,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.
    *
@@ -1130,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;
@@ -1176,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.
    *
@@ -1200,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;
@@ -1213,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;
 }
@@ -1350,5 +1374,5 @@ declare function isMappaError(err: unknown): err is MappaError;
  */
 declare function isInsufficientCreditsError(err: unknown): err is InsufficientCreditsError;
 //#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, 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