@productcraft/trawl 0.2.3 → 0.2.4

package/README.md

@@ -20,7 +20,7 @@ import: `npm install productcraft`.
 
 ## Usage
 
-```ts
+```ts before
 import { Trawl } from "@productcraft/trawl";
 
 // Reads PRODUCTCRAFT_API_KEY from the environment

package/dist/index.d.cts

@@ -487,6 +487,64 @@ interface components {
              */
             reason: string;
         };
+        /**
+         * CreditsLowEvent
+         * @description Your Trawl balance dropped below 10% of your last top-up (at least 100 steps). Sent once; it comes again after your next top-up. New jobs are refused when the balance reaches zero. Job events also carry the keys of the previous webhook body (`event`, `occurred_at`, `job`) until its sunset; read `type`, `created_at` and `data` instead.
+         * @example {
+         *       "created_at": "2026-11-05T09:00:00.000Z",
+         *       "data": {
+         *         "balance_steps": 840,
+         *         "last_top_up_steps": 10000,
+         *         "threshold_steps": 1000
+         *       },
+         *       "id": "evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
+         *       "type": "credits.low",
+         *       "workspace_id": "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b"
+         *     }
+         */
+        CreditsLowEvent: {
+            /**
+             * Format: date-time
+             * @description When the event happened (the same on every retry).
+             * @example 2026-11-05T09:00:00.000Z
+             */
+            created_at: string;
+            data: components["schemas"]["CreditsLowEventDataDto"];
+            /**
+             * @description The event id, also sent as `webhook-id`; the same on every retry and replay.
+             * @example evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
+             */
+            id: string;
+            /** @description Present and true only on a delivery made by "Send test"; its `data` is the catalogue example. */
+            test?: boolean;
+            /**
+             * @description The event type. Switch on it to narrow the event.
+             * @enum {string}
+             */
+            type: "credits.low";
+            /**
+             * Format: uuid
+             * @description The workspace the event belongs to, so you can route without opening `data`. Absent on "Send test" deliveries.
+             */
+            workspace_id?: string;
+        };
+        CreditsLowEventDataDto: {
+            /**
+             * @description The balance, in steps, when the event was sent.
+             * @example 840
+             */
+            balance_steps: number;
+            /**
+             * @description Steps added by the last top-up.
+             * @example 10000
+             */
+            last_top_up_steps: number;
+            /**
+             * @description The threshold it dropped below: 10% of the last top-up, at least 100 steps.
+             * @example 1000
+             */
+            threshold_steps: number;
+        };
         CreditsResponseDto: {
             /**
              * @description Remaining steps. One agent step uses one credit; new jobs are refused (402) at zero. Can dip slightly below zero, because a running job is always allowed to finish.
@@ -563,6 +621,54 @@ interface components {
              */
             status_code: number;
         };
+        JobEventDataDto: {
+            /** @description The job that finished. */
+            job: components["schemas"]["JobOutcomeDto"];
+        };
+        /**
+         * JobFailedEvent
+         * @description An extraction job stopped without a result: the page did not load, the agent ran out of steps or time, or the result did not match your schema. The reason is in data.job.error. Job events also carry the keys of the previous webhook body (`event`, `occurred_at`, `job`) until its sunset; read `type`, `created_at` and `data` instead.
+         * @example {
+         *       "created_at": "2026-11-05T09:00:00.000Z",
+         *       "data": {
+         *         "job": {
+         *           "error": "The job ran out of steps before it found the data.",
+         *           "id": "7c1e2a4b-5d3f-4e8a-9b6c-0d1e2f3a4b5c",
+         *           "result": null,
+         *           "status": "failed"
+         *         }
+         *       },
+         *       "id": "evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
+         *       "type": "job.failed",
+         *       "workspace_id": "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b"
+         *     }
+         */
+        JobFailedEvent: {
+            /**
+             * Format: date-time
+             * @description When the event happened (the same on every retry).
+             * @example 2026-11-05T09:00:00.000Z
+             */
+            created_at: string;
+            data: components["schemas"]["JobEventDataDto"];
+            /**
+             * @description The event id, also sent as `webhook-id`; the same on every retry and replay.
+             * @example evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
+             */
+            id: string;
+            /** @description Present and true only on a delivery made by "Send test"; its `data` is the catalogue example. */
+            test?: boolean;
+            /**
+             * @description The event type. Switch on it to narrow the event.
+             * @enum {string}
+             */
+            type: "job.failed";
+            /**
+             * Format: uuid
+             * @description The workspace the event belongs to, so you can route without opening `data`. Absent on "Send test" deliveries.
+             */
+            workspace_id?: string;
+        };
         JobListPaginationDto: {
             /** @description Whether another page follows. */
             has_more: boolean;
@@ -575,6 +681,36 @@ interface components {
             /** @description The cursor for the next page. */
             pagination: components["schemas"]["JobListPaginationDto"];
         };
+        JobOutcomeDto: {
+            /**
+             * @description Why the job stopped without a result; null when it succeeded.
+             * @example null
+             */
+            error: string | null;
+            /**
+             * Format: uuid
+             * @description The job id.
+             * @example 7c1e2a4b-5d3f-4e8a-9b6c-0d1e2f3a4b5c
+             */
+            id: string;
+            /**
+             * @description The extracted JSON, matching the JSON Schema the job was created with; null when the job failed.
+             * @example {
+             *       "price": null,
+             *       "title": "Example Domain"
+             *     }
+             */
+            result: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * @description `succeeded` on `job.succeeded`, `failed` on `job.failed`.
+             * @example succeeded
+             */
+            status: components["schemas"]["JobOutcomeStatus"];
+        };
+        /** @enum {string} */
+        JobOutcomeStatus: "succeeded" | "failed";
         JobResponseDto: {
             /** @description How many times a worker has picked the job up. */
             attempts: number;
@@ -638,6 +774,53 @@ interface components {
         };
         /** @enum {string} */
         JobStatus: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+        /**
+         * JobSucceededEvent
+         * @description An extraction job finished and its result matches your JSON Schema. The result is in data.job.result. Job events also carry the keys of the previous webhook body (`event`, `occurred_at`, `job`) until its sunset; read `type`, `created_at` and `data` instead.
+         * @example {
+         *       "created_at": "2026-11-05T09:00:00.000Z",
+         *       "data": {
+         *         "job": {
+         *           "error": null,
+         *           "id": "7c1e2a4b-5d3f-4e8a-9b6c-0d1e2f3a4b5c",
+         *           "result": {
+         *             "price": null,
+         *             "title": "Example Domain"
+         *           },
+         *           "status": "succeeded"
+         *         }
+         *       },
+         *       "id": "evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
+         *       "type": "job.succeeded",
+         *       "workspace_id": "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b"
+         *     }
+         */
+        JobSucceededEvent: {
+            /**
+             * Format: date-time
+             * @description When the event happened (the same on every retry).
+             * @example 2026-11-05T09:00:00.000Z
+             */
+            created_at: string;
+            data: components["schemas"]["JobEventDataDto"];
+            /**
+             * @description The event id, also sent as `webhook-id`; the same on every retry and replay.
+             * @example evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
+             */
+            id: string;
+            /** @description Present and true only on a delivery made by "Send test"; its `data` is the catalogue example. */
+            test?: boolean;
+            /**
+             * @description The event type. Switch on it to narrow the event.
+             * @enum {string}
+             */
+            type: "job.succeeded";
+            /**
+             * Format: uuid
+             * @description The workspace the event belongs to, so you can route without opening `data`. Absent on "Send test" deliveries.
+             */
+            workspace_id?: string;
+        };
         ListWebhookEndpointsResponseDto: {
             /** @description The endpoints, newest first. */
             data: components["schemas"]["WebhookEndpointDto"][];
@@ -1130,7 +1313,10 @@ interface components {
         };
         /** @enum {string} */
         WebhookEventStatus: "pending" | "delivered" | "failed" | "not_sent";
-        /** @enum {string} */
+        /**
+         * @description Every event type this product sends; `x-webhooks` maps each to its payload schema. New types can be added, so treat it as open.
+         * @enum {string}
+         */
         WebhookEventType: "job.succeeded" | "job.failed" | "credits.low";
         WebhookEventTypeDto: {
             /**

package/dist/index.d.ts

@@ -487,6 +487,64 @@ interface components {
              */
             reason: string;
         };
+        /**
+         * CreditsLowEvent
+         * @description Your Trawl balance dropped below 10% of your last top-up (at least 100 steps). Sent once; it comes again after your next top-up. New jobs are refused when the balance reaches zero. Job events also carry the keys of the previous webhook body (`event`, `occurred_at`, `job`) until its sunset; read `type`, `created_at` and `data` instead.
+         * @example {
+         *       "created_at": "2026-11-05T09:00:00.000Z",
+         *       "data": {
+         *         "balance_steps": 840,
+         *         "last_top_up_steps": 10000,
+         *         "threshold_steps": 1000
+         *       },
+         *       "id": "evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
+         *       "type": "credits.low",
+         *       "workspace_id": "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b"
+         *     }
+         */
+        CreditsLowEvent: {
+            /**
+             * Format: date-time
+             * @description When the event happened (the same on every retry).
+             * @example 2026-11-05T09:00:00.000Z
+             */
+            created_at: string;
+            data: components["schemas"]["CreditsLowEventDataDto"];
+            /**
+             * @description The event id, also sent as `webhook-id`; the same on every retry and replay.
+             * @example evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
+             */
+            id: string;
+            /** @description Present and true only on a delivery made by "Send test"; its `data` is the catalogue example. */
+            test?: boolean;
+            /**
+             * @description The event type. Switch on it to narrow the event.
+             * @enum {string}
+             */
+            type: "credits.low";
+            /**
+             * Format: uuid
+             * @description The workspace the event belongs to, so you can route without opening `data`. Absent on "Send test" deliveries.
+             */
+            workspace_id?: string;
+        };
+        CreditsLowEventDataDto: {
+            /**
+             * @description The balance, in steps, when the event was sent.
+             * @example 840
+             */
+            balance_steps: number;
+            /**
+             * @description Steps added by the last top-up.
+             * @example 10000
+             */
+            last_top_up_steps: number;
+            /**
+             * @description The threshold it dropped below: 10% of the last top-up, at least 100 steps.
+             * @example 1000
+             */
+            threshold_steps: number;
+        };
         CreditsResponseDto: {
             /**
              * @description Remaining steps. One agent step uses one credit; new jobs are refused (402) at zero. Can dip slightly below zero, because a running job is always allowed to finish.
@@ -563,6 +621,54 @@ interface components {
              */
             status_code: number;
         };
+        JobEventDataDto: {
+            /** @description The job that finished. */
+            job: components["schemas"]["JobOutcomeDto"];
+        };
+        /**
+         * JobFailedEvent
+         * @description An extraction job stopped without a result: the page did not load, the agent ran out of steps or time, or the result did not match your schema. The reason is in data.job.error. Job events also carry the keys of the previous webhook body (`event`, `occurred_at`, `job`) until its sunset; read `type`, `created_at` and `data` instead.
+         * @example {
+         *       "created_at": "2026-11-05T09:00:00.000Z",
+         *       "data": {
+         *         "job": {
+         *           "error": "The job ran out of steps before it found the data.",
+         *           "id": "7c1e2a4b-5d3f-4e8a-9b6c-0d1e2f3a4b5c",
+         *           "result": null,
+         *           "status": "failed"
+         *         }
+         *       },
+         *       "id": "evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
+         *       "type": "job.failed",
+         *       "workspace_id": "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b"
+         *     }
+         */
+        JobFailedEvent: {
+            /**
+             * Format: date-time
+             * @description When the event happened (the same on every retry).
+             * @example 2026-11-05T09:00:00.000Z
+             */
+            created_at: string;
+            data: components["schemas"]["JobEventDataDto"];
+            /**
+             * @description The event id, also sent as `webhook-id`; the same on every retry and replay.
+             * @example evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
+             */
+            id: string;
+            /** @description Present and true only on a delivery made by "Send test"; its `data` is the catalogue example. */
+            test?: boolean;
+            /**
+             * @description The event type. Switch on it to narrow the event.
+             * @enum {string}
+             */
+            type: "job.failed";
+            /**
+             * Format: uuid
+             * @description The workspace the event belongs to, so you can route without opening `data`. Absent on "Send test" deliveries.
+             */
+            workspace_id?: string;
+        };
         JobListPaginationDto: {
             /** @description Whether another page follows. */
             has_more: boolean;
@@ -575,6 +681,36 @@ interface components {
             /** @description The cursor for the next page. */
             pagination: components["schemas"]["JobListPaginationDto"];
         };
+        JobOutcomeDto: {
+            /**
+             * @description Why the job stopped without a result; null when it succeeded.
+             * @example null
+             */
+            error: string | null;
+            /**
+             * Format: uuid
+             * @description The job id.
+             * @example 7c1e2a4b-5d3f-4e8a-9b6c-0d1e2f3a4b5c
+             */
+            id: string;
+            /**
+             * @description The extracted JSON, matching the JSON Schema the job was created with; null when the job failed.
+             * @example {
+             *       "price": null,
+             *       "title": "Example Domain"
+             *     }
+             */
+            result: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * @description `succeeded` on `job.succeeded`, `failed` on `job.failed`.
+             * @example succeeded
+             */
+            status: components["schemas"]["JobOutcomeStatus"];
+        };
+        /** @enum {string} */
+        JobOutcomeStatus: "succeeded" | "failed";
         JobResponseDto: {
             /** @description How many times a worker has picked the job up. */
             attempts: number;
@@ -638,6 +774,53 @@ interface components {
         };
         /** @enum {string} */
         JobStatus: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+        /**
+         * JobSucceededEvent
+         * @description An extraction job finished and its result matches your JSON Schema. The result is in data.job.result. Job events also carry the keys of the previous webhook body (`event`, `occurred_at`, `job`) until its sunset; read `type`, `created_at` and `data` instead.
+         * @example {
+         *       "created_at": "2026-11-05T09:00:00.000Z",
+         *       "data": {
+         *         "job": {
+         *           "error": null,
+         *           "id": "7c1e2a4b-5d3f-4e8a-9b6c-0d1e2f3a4b5c",
+         *           "result": {
+         *             "price": null,
+         *             "title": "Example Domain"
+         *           },
+         *           "status": "succeeded"
+         *         }
+         *       },
+         *       "id": "evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
+         *       "type": "job.succeeded",
+         *       "workspace_id": "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b"
+         *     }
+         */
+        JobSucceededEvent: {
+            /**
+             * Format: date-time
+             * @description When the event happened (the same on every retry).
+             * @example 2026-11-05T09:00:00.000Z
+             */
+            created_at: string;
+            data: components["schemas"]["JobEventDataDto"];
+            /**
+             * @description The event id, also sent as `webhook-id`; the same on every retry and replay.
+             * @example evt_3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
+             */
+            id: string;
+            /** @description Present and true only on a delivery made by "Send test"; its `data` is the catalogue example. */
+            test?: boolean;
+            /**
+             * @description The event type. Switch on it to narrow the event.
+             * @enum {string}
+             */
+            type: "job.succeeded";
+            /**
+             * Format: uuid
+             * @description The workspace the event belongs to, so you can route without opening `data`. Absent on "Send test" deliveries.
+             */
+            workspace_id?: string;
+        };
         ListWebhookEndpointsResponseDto: {
             /** @description The endpoints, newest first. */
             data: components["schemas"]["WebhookEndpointDto"][];
@@ -1130,7 +1313,10 @@ interface components {
         };
         /** @enum {string} */
         WebhookEventStatus: "pending" | "delivered" | "failed" | "not_sent";
-        /** @enum {string} */
+        /**
+         * @description Every event type this product sends; `x-webhooks` maps each to its payload schema. New types can be added, so treat it as open.
+         * @enum {string}
+         */
         WebhookEventType: "job.succeeded" | "job.failed" | "credits.low";
         WebhookEventTypeDto: {
             /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@productcraft/trawl",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "AI web-extraction — submit a JSON Schema + natural-language description, get schema-conforming data extracted from the live web and delivered to an HMAC-signed webhook via ProductCraft Trawl. Generated from the production OpenAPI spec.",
   "type": "module",
   "main": "./dist/index.cjs",