@mappa-ai/mappa-node 1.2.3 → 1.2.4

package/dist/index.d.cts

@@ -1303,9 +1303,52 @@ declare class ReportsResource {
 }
 //#endregion
 //#region src/resources/webhooks.d.ts
+/**
+ * Webhook event types supported by the API.
+ */
+type WebhookEventType = "report.completed" | "report.failed";
+/**
+ * Base webhook event structure.
+ */
+interface WebhookEvent<T = unknown> {
+  type: string;
+  timestamp: string;
+  data: T;
+}
+/**
+ * Payload for successful report completion.
+ */
+interface ReportCompletedData {
+  jobId: string;
+  reportId: string;
+  status: "succeeded";
+}
+/**
+ * Payload for failed report processing.
+ */
+interface ReportFailedData {
+  jobId: string;
+  status: "failed";
+  error: {
+    code: string;
+    message: string;
+  };
+}
+/**
+ * Event emitted when a report completes successfully.
+ */
+type ReportCompletedEvent = WebhookEvent<ReportCompletedData> & {
+  type: "report.completed";
+};
+/**
+ * Event emitted when a report fails.
+ */
+type ReportFailedEvent = WebhookEvent<ReportFailedData> & {
+  type: "report.failed";
+};
 /**
  * Async signature verification using WebCrypto (works in modern Node and browsers).
- * Signature scheme placeholder:
+ * Signature scheme:
  *   headers["mappa-signature"] = "t=1700000000,v1=<hex_hmac_sha256>"
  * Signed payload: `${t}.${rawBody}`
  */
@@ -1318,12 +1361,14 @@ declare class WebhooksResource {
   }): Promise<{
     ok: true;
   }>;
-  parseEvent<T = unknown>(payload: string): {
-    id: string;
-    type: string;
-    createdAt: string;
-    data: T;
-  };
+  /**
+   * Parse and validate a webhook event payload.
+   *
+   * @param payload - Raw JSON string from the webhook request body
+   * @returns Parsed and validated webhook event
+   * @throws Error if payload is invalid or missing required fields
+   */
+  parseEvent<T = unknown>(payload: string): WebhookEvent<T>;
 }
 //#endregion
 //#region src/Mappa.d.ts
@@ -1437,5 +1482,5 @@ declare function isInsufficientCreditsError(err: unknown): err is InsufficientCr
  */
 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, 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 };
+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, type ReportCompletedData, type ReportCompletedEvent, ReportCreateJobRequest, type ReportFailedData, type ReportFailedEvent, 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, type WebhookEvent, type WebhookEventType, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isStreamError, isUrlReport };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1303,9 +1303,52 @@ declare class ReportsResource {
 }
 //#endregion
 //#region src/resources/webhooks.d.ts
+/**
+ * Webhook event types supported by the API.
+ */
+type WebhookEventType = "report.completed" | "report.failed";
+/**
+ * Base webhook event structure.
+ */
+interface WebhookEvent<T = unknown> {
+  type: string;
+  timestamp: string;
+  data: T;
+}
+/**
+ * Payload for successful report completion.
+ */
+interface ReportCompletedData {
+  jobId: string;
+  reportId: string;
+  status: "succeeded";
+}
+/**
+ * Payload for failed report processing.
+ */
+interface ReportFailedData {
+  jobId: string;
+  status: "failed";
+  error: {
+    code: string;
+    message: string;
+  };
+}
+/**
+ * Event emitted when a report completes successfully.
+ */
+type ReportCompletedEvent = WebhookEvent<ReportCompletedData> & {
+  type: "report.completed";
+};
+/**
+ * Event emitted when a report fails.
+ */
+type ReportFailedEvent = WebhookEvent<ReportFailedData> & {
+  type: "report.failed";
+};
 /**
  * Async signature verification using WebCrypto (works in modern Node and browsers).
- * Signature scheme placeholder:
+ * Signature scheme:
  *   headers["mappa-signature"] = "t=1700000000,v1=<hex_hmac_sha256>"
  * Signed payload: `${t}.${rawBody}`
  */
@@ -1318,12 +1361,14 @@ declare class WebhooksResource {
   }): Promise<{
     ok: true;
   }>;
-  parseEvent<T = unknown>(payload: string): {
-    id: string;
-    type: string;
-    createdAt: string;
-    data: T;
-  };
+  /**
+   * Parse and validate a webhook event payload.
+   *
+   * @param payload - Raw JSON string from the webhook request body
+   * @returns Parsed and validated webhook event
+   * @throws Error if payload is invalid or missing required fields
+   */
+  parseEvent<T = unknown>(payload: string): WebhookEvent<T>;
 }
 //#endregion
 //#region src/Mappa.d.ts
@@ -1437,5 +1482,5 @@ declare function isInsufficientCreditsError(err: unknown): err is InsufficientCr
  */
 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, 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 };
+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, type ReportCompletedData, type ReportCompletedEvent, ReportCreateJobRequest, type ReportFailedData, type ReportFailedEvent, 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, type WebhookEvent, type WebhookEventType, hasEntity, isInsufficientCreditsError, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isStreamError, isUrlReport };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1614,7 +1614,7 @@ function isObject(v) {
 }
 /**
 * Async signature verification using WebCrypto (works in modern Node and browsers).
-* Signature scheme placeholder:
+* Signature scheme:
 *   headers["mappa-signature"] = "t=1700000000,v1=<hex_hmac_sha256>"
 * Signed payload: `${t}.${rawBody}`
 */
@@ -1632,20 +1632,24 @@ var WebhooksResource = class {
 		if (!timingSafeEqualHex(await hmacHex(params.secret, signed), parts.v1)) throw new Error("Invalid signature");
 		return { ok: true };
 	}
+	/**
+	* Parse and validate a webhook event payload.
+	*
+	* @param payload - Raw JSON string from the webhook request body
+	* @returns Parsed and validated webhook event
+	* @throws Error if payload is invalid or missing required fields
+	*/
 	parseEvent(payload) {
 		const raw = JSON.parse(payload);
 		if (!isObject(raw)) throw new Error("Invalid webhook payload: not an object");
 		const obj = raw;
-		const id = obj.id;
 		const type = obj.type;
-		const createdAt = obj.createdAt;
-		if (typeof id !== "string") throw new Error("Invalid webhook payload: id must be a string");
+		const timestamp = obj.timestamp;
 		if (typeof type !== "string") throw new Error("Invalid webhook payload: type must be a string");
-		if (typeof createdAt !== "string") throw new Error("Invalid webhook payload: createdAt must be a string");
+		if (typeof timestamp !== "string") throw new Error("Invalid webhook payload: timestamp must be a string");
 		return {
-			id,
 			type,
-			createdAt,
+			timestamp,
 			data: "data" in obj ? obj.data : void 0
 		};
 	}