@productcraft/trawl 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProductCraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @productcraft/trawl
+
+Typed Node.js / TypeScript client for **ProductCraft Trawl** — AI web
+extraction. Hand Trawl a JSON Schema plus a natural-language description
+(and optional seed URLs); a browser agent navigates the live web, extracts
+data conforming to your schema, and the result is delivered to a
+preconfigured HMAC-signed webhook.
+
+Generated from the production OpenAPI spec, so every endpoint is reachable
+and fully typed.
+
+## Install
+
+```sh
+npm install @productcraft/trawl
+```
+
+Or use the umbrella package to get every ProductCraft surface from one
+import: `npm install productcraft`.
+
+## Usage
+
+```ts
+import { Trawl } from "@productcraft/trawl";
+
+const trawl = new Trawl({ auth: { type: "apiKey", key: process.env.PCFT_KEY! } });
+
+// Submit an extraction job (workspace-scoped).
+const { data, error } = await trawl.client.POST(
+  "/v1/workspaces/{workspaceId}/jobs",
+  {
+    params: { path: { workspaceId: "ws_..." } },
+    body: {
+      description: "Extract the product title and price from each page.",
+      json_schema: {
+        type: "object",
+        properties: { title: { type: "string" }, price: { type: "number" } },
+        required: ["title"],
+      },
+      suggested_urls: ["https://example.com/product"],
+    },
+  },
+);
+
+if (error) throw error;
+console.log(data.id, data.status); // → "job_...", "queued"
+```
+
+Poll `GET /v1/workspaces/{workspaceId}/jobs/{id}` for the result, or
+register a webhook (`POST /v1/workspaces/{workspaceId}/webhooks`) to have
+the terminal result delivered to you. Job submission is rate-limited per
+workspace (default 10/min); a `429` carries a `Retry-After` header.
+
+## Auth
+
+Pass a workspace API key (`pcft_live_*`) as `{ type: "apiKey", key }`. The
+client sets `Authorization: Bearer <key>` on every request.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var core = require('@productcraft/core');
+
+// src/index.ts
+var Trawl = class {
+  /** The underlying typed client. v0 surface — every endpoint reachable. */
+  client;
+  constructor(config = {}) {
+    this.client = core.makeClient(core.PC_BASE_URL.trawl, config);
+  }
+};
+
+exports.Trawl = Trawl;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["makeClient","PC_BASE_URL"],"mappings":";;;;;AASO,IAAM,QAAN,MAAY;AAAA;AAAA,EAED,MAAA;AAAA,EAEhB,WAAA,CAAY,MAAA,GAAyB,EAAC,EAAG;AACvC,IAAA,IAAA,CAAK,MAAA,GAASA,eAAA,CAAkBC,gBAAA,CAAY,KAAA,EAAO,MAAM,CAAA;AAAA,EAC3D;AACF","file":"index.cjs","sourcesContent":["import type { paths } from \"./_generated.js\";\nimport { makeClient, PC_BASE_URL, type PCClientConfig } from \"@productcraft/core\";\n\n/**\n * Trawl — typed `openapi-fetch` client for every endpoint in\n * `Specs/trawl.json`. Reach for `client.GET(\"/v1/...\")` or\n * `client.POST(...)`; request / response types come from the\n * generated `paths` interface.\n */\nexport class Trawl {\n  /** The underlying typed client. v0 surface — every endpoint reachable. */\n  public readonly client: ReturnType<typeof makeClient<paths>>;\n\n  constructor(config: PCClientConfig = {}) {\n    this.client = makeClient<paths>(PC_BASE_URL.trawl, config);\n  }\n}\n\nexport type { paths } from \"./_generated.js\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,606 @@
+import { makeClient, PCClientConfig } from '@productcraft/core';
+
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+interface paths {
+    "/v1/workspaces/{workspace_id}/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List trawl jobs (paginated, newest first) */
+        get: operations["JobController_list"];
+        put?: never;
+        /** Create (enqueue) a trawl job */
+        post: operations["JobController_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/jobs/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get a single trawl job */
+        get: operations["JobController_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/jobs/{id}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Cancel a queued or running trawl job */
+        post: operations["JobController_cancel"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List webhooks for the workspace (secrets masked) */
+        get: operations["WebhookController_list"];
+        put?: never;
+        /** Create a workspace webhook. The response includes the signing secret in clear EXACTLY ONCE — copy it now. */
+        post: operations["WebhookController_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get a webhook (secret masked) */
+        get: operations["WebhookController_get"];
+        put?: never;
+        post?: never;
+        /** Delete a webhook */
+        delete: operations["WebhookController_remove"];
+        options?: never;
+        head?: never;
+        /** Update url / active flag (active=true clears auto-disable) */
+        patch: operations["WebhookController_update"];
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}/deliveries": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Recent delivery attempts for a webhook (default 50, max 200, newest first) */
+        get: operations["WebhookController_recentDeliveries"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Rotate the signing secret. Returns the new secret in clear EXACTLY ONCE. */
+        post: operations["WebhookController_rotateSecret"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}/test": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Fire a synthetic event to this webhook (asynchronous; check the destination logs) */
+        post: operations["WebhookController_fireTest"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        CreateJobDto: {
+            /**
+             * @description Natural-language description of what to extract.
+             * @example Extract the product title and price from each page.
+             */
+            description: string;
+            /**
+             * @description JSON Schema describing the shape of the extraction result. Must be a non-empty object with `type: "object"`.
+             * @example {
+             *       "properties": {
+             *         "title": {
+             *           "type": "string"
+             *         }
+             *       },
+             *       "required": [
+             *         "title"
+             *       ],
+             *       "type": "object"
+             *     }
+             */
+            json_schema: Record<string, never>;
+            /** @description Maximum number of worker steps before the job stops. */
+            max_steps?: number;
+            /** @description Model tier the worker should use (e.g. `standard`, `pro`). */
+            model_tier?: string;
+            /** @description Seed URLs the worker should start from. */
+            suggested_urls?: string[];
+            /** @description Wall-clock timeout for the job, in seconds. */
+            timeout_s?: number;
+            /** @description Webhook id to notify when the job finishes. */
+            webhook_id?: string;
+        };
+        CreateWebhookDto: {
+            /** @description Disabled webhooks are never delivered to. */
+            active?: boolean;
+            /** @description Destination URL (https required in prod). */
+            url: string;
+        };
+        JobListPaginationDto: {
+            has_more: boolean;
+            next_cursor: string | null;
+        };
+        JobListResponseDto: {
+            data: components["schemas"]["JobResponseDto"][];
+            pagination: components["schemas"]["JobListPaginationDto"];
+        };
+        JobResponseDto: {
+            attempts: number;
+            completed_at: string | null;
+            created_at: string;
+            description: string;
+            enqueued_at: string;
+            error: string | null;
+            id: string;
+            json_schema: Record<string, never>;
+            max_steps: number;
+            model_tier: string;
+            result: Record<string, never> | null;
+            started_at: string | null;
+            /** @enum {string} */
+            status: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+            suggested_urls: string[] | null;
+            timeout_s: number;
+            webhook_id: string | null;
+            workspace_id: string;
+        };
+        UpdateWebhookDto: {
+            /** @description Pause/resume the webhook. Setting active=true clears auto-disable. */
+            active?: boolean;
+            /** @description New destination URL. */
+            url?: string;
+        };
+        WebhookCreateResponseDto: {
+            active: boolean;
+            auto_disabled_at: string | null;
+            created_at: string;
+            failure_count: number;
+            first_failure_at: string | null;
+            id: string;
+            last_attempt_at: string | null;
+            last_status_code: number | null;
+            /** @description Plaintext signing secret returned EXACTLY ONCE on create + rotate. Persist immediately — it never appears on subsequent GETs. */
+            signing_secret: string;
+            url: string;
+            workspace_id: string;
+        };
+        WebhookListResponseDto: {
+            data: components["schemas"]["WebhookResponseDto"][];
+        };
+        WebhookResponseDto: {
+            active: boolean;
+            auto_disabled_at: string | null;
+            created_at: string;
+            failure_count: number;
+            first_failure_at: string | null;
+            id: string;
+            last_attempt_at: string | null;
+            last_status_code: number | null;
+            url: string;
+            workspace_id: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    JobController_list: {
+        parameters: {
+            query?: {
+                /** @description Filter by job status. */
+                status?: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+                /** @description Opaque cursor for pagination. */
+                cursor?: string;
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Page of jobs with pagination cursor. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobListResponseDto"];
+                };
+            };
+            /** @description Caller lacks `trawl.list`, or workspace has not enabled the `trawl` service. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    JobController_create: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Pass a key (1..256 chars, [A-Za-z0-9_\-:]) to make retries safe — replays return the original response for 24h. */
+                "Idempotency-Key"?: string;
+            };
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateJobDto"];
+            };
+        };
+        responses: {
+            /** @description Job created and queued. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobResponseDto"];
+                };
+            };
+            /** @description Invalid JSON Schema (must be a non-empty `type: object`). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Caller lacks `trawl.create`, or workspace has not enabled the `trawl` service. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    JobController_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Job row. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobResponseDto"];
+                };
+            };
+            /** @description Job not found in this workspace. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    JobController_cancel: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Job cancelled. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobResponseDto"];
+                };
+            };
+            /** @description Job not found in this workspace. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Job is already in a terminal state and cannot be cancelled. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_list: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookListResponseDto"];
+                };
+            };
+        };
+    };
+    WebhookController_create: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Stripe-style idempotency key. The signing secret is returned exactly once; a retry without this header creates a second webhook + secret. 24h TTL. */
+                "Idempotency-Key"?: string;
+            };
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateWebhookDto"];
+            };
+        };
+        responses: {
+            /** @description Webhook created. Includes plaintext `signing_secret` exactly once. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookCreateResponseDto"];
+                };
+            };
+        };
+    };
+    WebhookController_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookResponseDto"];
+                };
+            };
+            /** @description Webhook not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_remove: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_update: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateWebhookDto"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookResponseDto"];
+                };
+            };
+        };
+    };
+    WebhookController_recentDeliveries: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Recent delivery attempts. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_rotateSecret: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_fireTest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+}
+
+/**
+ * Trawl — typed `openapi-fetch` client for every endpoint in
+ * `Specs/trawl.json`. Reach for `client.GET("/v1/...")` or
+ * `client.POST(...)`; request / response types come from the
+ * generated `paths` interface.
+ */
+declare class Trawl {
+    /** The underlying typed client. v0 surface — every endpoint reachable. */
+    readonly client: ReturnType<typeof makeClient<paths>>;
+    constructor(config?: PCClientConfig);
+}
+
+export { Trawl, type paths };

package/dist/index.d.ts

@@ -0,0 +1,606 @@
+import { makeClient, PCClientConfig } from '@productcraft/core';
+
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+interface paths {
+    "/v1/workspaces/{workspace_id}/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List trawl jobs (paginated, newest first) */
+        get: operations["JobController_list"];
+        put?: never;
+        /** Create (enqueue) a trawl job */
+        post: operations["JobController_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/jobs/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get a single trawl job */
+        get: operations["JobController_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/jobs/{id}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Cancel a queued or running trawl job */
+        post: operations["JobController_cancel"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List webhooks for the workspace (secrets masked) */
+        get: operations["WebhookController_list"];
+        put?: never;
+        /** Create a workspace webhook. The response includes the signing secret in clear EXACTLY ONCE — copy it now. */
+        post: operations["WebhookController_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get a webhook (secret masked) */
+        get: operations["WebhookController_get"];
+        put?: never;
+        post?: never;
+        /** Delete a webhook */
+        delete: operations["WebhookController_remove"];
+        options?: never;
+        head?: never;
+        /** Update url / active flag (active=true clears auto-disable) */
+        patch: operations["WebhookController_update"];
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}/deliveries": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Recent delivery attempts for a webhook (default 50, max 200, newest first) */
+        get: operations["WebhookController_recentDeliveries"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Rotate the signing secret. Returns the new secret in clear EXACTLY ONCE. */
+        post: operations["WebhookController_rotateSecret"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/webhooks/{id}/test": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Fire a synthetic event to this webhook (asynchronous; check the destination logs) */
+        post: operations["WebhookController_fireTest"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        CreateJobDto: {
+            /**
+             * @description Natural-language description of what to extract.
+             * @example Extract the product title and price from each page.
+             */
+            description: string;
+            /**
+             * @description JSON Schema describing the shape of the extraction result. Must be a non-empty object with `type: "object"`.
+             * @example {
+             *       "properties": {
+             *         "title": {
+             *           "type": "string"
+             *         }
+             *       },
+             *       "required": [
+             *         "title"
+             *       ],
+             *       "type": "object"
+             *     }
+             */
+            json_schema: Record<string, never>;
+            /** @description Maximum number of worker steps before the job stops. */
+            max_steps?: number;
+            /** @description Model tier the worker should use (e.g. `standard`, `pro`). */
+            model_tier?: string;
+            /** @description Seed URLs the worker should start from. */
+            suggested_urls?: string[];
+            /** @description Wall-clock timeout for the job, in seconds. */
+            timeout_s?: number;
+            /** @description Webhook id to notify when the job finishes. */
+            webhook_id?: string;
+        };
+        CreateWebhookDto: {
+            /** @description Disabled webhooks are never delivered to. */
+            active?: boolean;
+            /** @description Destination URL (https required in prod). */
+            url: string;
+        };
+        JobListPaginationDto: {
+            has_more: boolean;
+            next_cursor: string | null;
+        };
+        JobListResponseDto: {
+            data: components["schemas"]["JobResponseDto"][];
+            pagination: components["schemas"]["JobListPaginationDto"];
+        };
+        JobResponseDto: {
+            attempts: number;
+            completed_at: string | null;
+            created_at: string;
+            description: string;
+            enqueued_at: string;
+            error: string | null;
+            id: string;
+            json_schema: Record<string, never>;
+            max_steps: number;
+            model_tier: string;
+            result: Record<string, never> | null;
+            started_at: string | null;
+            /** @enum {string} */
+            status: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+            suggested_urls: string[] | null;
+            timeout_s: number;
+            webhook_id: string | null;
+            workspace_id: string;
+        };
+        UpdateWebhookDto: {
+            /** @description Pause/resume the webhook. Setting active=true clears auto-disable. */
+            active?: boolean;
+            /** @description New destination URL. */
+            url?: string;
+        };
+        WebhookCreateResponseDto: {
+            active: boolean;
+            auto_disabled_at: string | null;
+            created_at: string;
+            failure_count: number;
+            first_failure_at: string | null;
+            id: string;
+            last_attempt_at: string | null;
+            last_status_code: number | null;
+            /** @description Plaintext signing secret returned EXACTLY ONCE on create + rotate. Persist immediately — it never appears on subsequent GETs. */
+            signing_secret: string;
+            url: string;
+            workspace_id: string;
+        };
+        WebhookListResponseDto: {
+            data: components["schemas"]["WebhookResponseDto"][];
+        };
+        WebhookResponseDto: {
+            active: boolean;
+            auto_disabled_at: string | null;
+            created_at: string;
+            failure_count: number;
+            first_failure_at: string | null;
+            id: string;
+            last_attempt_at: string | null;
+            last_status_code: number | null;
+            url: string;
+            workspace_id: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    JobController_list: {
+        parameters: {
+            query?: {
+                /** @description Filter by job status. */
+                status?: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+                /** @description Opaque cursor for pagination. */
+                cursor?: string;
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Page of jobs with pagination cursor. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobListResponseDto"];
+                };
+            };
+            /** @description Caller lacks `trawl.list`, or workspace has not enabled the `trawl` service. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    JobController_create: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Pass a key (1..256 chars, [A-Za-z0-9_\-:]) to make retries safe — replays return the original response for 24h. */
+                "Idempotency-Key"?: string;
+            };
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateJobDto"];
+            };
+        };
+        responses: {
+            /** @description Job created and queued. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobResponseDto"];
+                };
+            };
+            /** @description Invalid JSON Schema (must be a non-empty `type: object`). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Caller lacks `trawl.create`, or workspace has not enabled the `trawl` service. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    JobController_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Job row. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobResponseDto"];
+                };
+            };
+            /** @description Job not found in this workspace. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    JobController_cancel: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Job cancelled. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["JobResponseDto"];
+                };
+            };
+            /** @description Job not found in this workspace. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Job is already in a terminal state and cannot be cancelled. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_list: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookListResponseDto"];
+                };
+            };
+        };
+    };
+    WebhookController_create: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Stripe-style idempotency key. The signing secret is returned exactly once; a retry without this header creates a second webhook + secret. 24h TTL. */
+                "Idempotency-Key"?: string;
+            };
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateWebhookDto"];
+            };
+        };
+        responses: {
+            /** @description Webhook created. Includes plaintext `signing_secret` exactly once. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookCreateResponseDto"];
+                };
+            };
+        };
+    };
+    WebhookController_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookResponseDto"];
+                };
+            };
+            /** @description Webhook not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_remove: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_update: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateWebhookDto"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WebhookResponseDto"];
+                };
+            };
+        };
+    };
+    WebhookController_recentDeliveries: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Recent delivery attempts. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_rotateSecret: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WebhookController_fireTest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+}
+
+/**
+ * Trawl — typed `openapi-fetch` client for every endpoint in
+ * `Specs/trawl.json`. Reach for `client.GET("/v1/...")` or
+ * `client.POST(...)`; request / response types come from the
+ * generated `paths` interface.
+ */
+declare class Trawl {
+    /** The underlying typed client. v0 surface — every endpoint reachable. */
+    readonly client: ReturnType<typeof makeClient<paths>>;
+    constructor(config?: PCClientConfig);
+}
+
+export { Trawl, type paths };

package/dist/index.js

@@ -0,0 +1,14 @@
+import { makeClient, PC_BASE_URL } from '@productcraft/core';
+
+// src/index.ts
+var Trawl = class {
+  /** The underlying typed client. v0 surface — every endpoint reachable. */
+  client;
+  constructor(config = {}) {
+    this.client = makeClient(PC_BASE_URL.trawl, config);
+  }
+};
+
+export { Trawl };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AASO,IAAM,QAAN,MAAY;AAAA;AAAA,EAED,MAAA;AAAA,EAEhB,WAAA,CAAY,MAAA,GAAyB,EAAC,EAAG;AACvC,IAAA,IAAA,CAAK,MAAA,GAAS,UAAA,CAAkB,WAAA,CAAY,KAAA,EAAO,MAAM,CAAA;AAAA,EAC3D;AACF","file":"index.js","sourcesContent":["import type { paths } from \"./_generated.js\";\nimport { makeClient, PC_BASE_URL, type PCClientConfig } from \"@productcraft/core\";\n\n/**\n * Trawl — typed `openapi-fetch` client for every endpoint in\n * `Specs/trawl.json`. Reach for `client.GET(\"/v1/...\")` or\n * `client.POST(...)`; request / response types come from the\n * generated `paths` interface.\n */\nexport class Trawl {\n  /** The underlying typed client. v0 surface — every endpoint reachable. */\n  public readonly client: ReturnType<typeof makeClient<paths>>;\n\n  constructor(config: PCClientConfig = {}) {\n    this.client = makeClient<paths>(PC_BASE_URL.trawl, config);\n  }\n}\n\nexport type { paths } from \"./_generated.js\";\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@productcraft/trawl",
+  "version": "0.1.0",
+  "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",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "productcraft",
+    "sdk",
+    "trawl",
+    "web-extraction",
+    "scraping"
+  ],
+  "author": "ProductCraft",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clauderanelagh/productcraft-node.git",
+    "directory": "packages/trawl"
+  },
+  "homepage": "https://github.com/clauderanelagh/productcraft-node/tree/main/packages/trawl",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.13.0",
+    "@productcraft/core": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}