@scrapyio/sdk 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# @scrapyio/sdk
+
+Official TypeScript / JavaScript SDK for [Scrapy.io](https://scrapy.io).
+
+**Node / server-first.** Keep API keys on the server — never ship them in browser apps.
+
+## Install
+
+```bash
+npm install @scrapyio/sdk
+```
+
+(Until publish: `npm install ./scrapyio-sdk-0.1.0.tgz` from a local pack.)
+
+## Authentication
+
+```ts
+import { ScrapyIO } from '@scrapyio/sdk';
+
+const client = new ScrapyIO({
+  apiKey: process.env.SCRAPYIO_API_KEY!, // or SCRAPY_API_KEY
+});
+```
+
+The SDK always sends:
+
+```http
+Authorization: Bearer <apiKey>
+```
+
+Missing/blank keys throw `ScrapyIOError` immediately. Invalid keys produce `type: "unauthorized"` (HTTP 401).
+
+## First request
+
+```ts
+const tools = await client.tools.list({ q: 'instagram', limit: 20 });
+// { items, total, offset, limit }
+
+const tool = await client.tools.get('datadoping', 'instagram-profile-scraper');
+// or:
+const same = await client.tool('datadoping/instagram-profile-scraper').get();
+
+console.log(tool.inputSchema, tool.execution.apiUrl);
+```
+
+## Run a scraper
+
+### Sync (`/v1/api`) — one primary input
+
+```ts
+const result = await client.tool('datadoping/instagram-profile-scraper').call({
+  username: 'nasa',
+});
+```
+
+### Async (`/v1/scraper`) — batch + poll
+
+```ts
+const run = await client.tool('datadoping/instagram-profile-scraper').start({
+  usernames: ['nasa'],
+});
+
+const finished = await client.run(run.id).wait({
+  pollIntervalMs: 3000,
+  timeoutMs: 15 * 60_000,
+});
+
+const page = await client.run(run.id).listItems({ offset: 0, limit: 100 });
+// { items, total, offset, limit } — rows are Record<string, unknown>
+```
+
+Public run statuses: `queued` | `running` | `succeeded` | `partial` | `failed` | `cancelled`.
+
+## Schedules
+
+```ts
+const schedule = await client.schedules.create(
+  {
+    publisher: 'datadoping',
+    slug: 'instagram-profile-scraper',
+    runName: 'nightly-ig',
+    timezone: 'UTC',
+    frequency: 'one-time',
+    date: '2026-09-20',
+    time: '23:50',
+    inputs: ['nasa'],
+  },
+  { idempotencyKey: 'nightly-ig-v1' }
+);
+
+// PATCH: exactly one of isActive | notificationsEnabled
+await client.schedules.update(schedule.id, { isActive: false });
+await client.schedules.delete(schedule.id);
+```
+
+## Errors
+
+```ts
+import { ScrapyIO, ScrapyIOError } from '@scrapyio/sdk';
+
+try {
+  await client.tools.get('nope', 'missing');
+} catch (err) {
+  if (err instanceof ScrapyIOError) {
+    // type, status, message, docUrl
+  }
+}
+```
+
+## Mental model
+
+```text
+client
+├── tools.list / tools.get
+├── tool("publisher/slug").get / .call / .start
+├── runs.list / runs.get
+├── run(id).get / .wait / .listItems
+└── schedules.list / get / create / update / delete
+```
+
+## Development / verification
+
+```bash
+cd sdk/js
+npm install
+npm run generate
+npm run check          # openapi lint + generate + typecheck + unit tests
+npm run build
+npm pack --dry-run
+
+# Real API (requires sdk/js/.env — never commit)
+cd ../backend && npx tsx ../sdk/js/scripts/bootstrap-integration-env.ts
+cd ../sdk/js && npm run test:integration
+```
+
+## Notes
+
+- GET requests may retry on transient 5xx/429; execution `POST`s and schedule creates are **not** auto-retried (use `idempotencyKey` for schedule creates).
+- `listItems()` is JSON-only in v0.1.
+- Async run `failed` can still return dataset rows (e.g. per-item errors); that is Platform behavior, not an SDK envelope bug.

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import { ToolHandle } from './tool.js';
+import { ToolsResource } from './tools.js';
+import { RunsResource } from './runs.js';
+import { RunHandle } from './run.js';
+import { SchedulesResource } from './schedules.js';
+import type { ScrapyIOOptions } from './types.js';
+/**
+ * Official Scrapy.io TypeScript SDK.
+ *
+ * API keys must stay server-side. Do not embed keys in browser apps.
+ */
+export declare class ScrapyIO {
+    readonly tools: ToolsResource;
+    readonly runs: RunsResource;
+    readonly schedules: SchedulesResource;
+    private readonly apiKey;
+    private readonly platform;
+    private readonly fetchImpl;
+    constructor(options: ScrapyIOOptions);
+    /** Lightweight tool handle (`publisher/slug`). Does not hit the network. */
+    tool(ref: string): ToolHandle;
+    /** Lightweight run handle. Does not hit the network. */
+    run(runId: string): RunHandle;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;gBAExC,OAAO,EAAE,eAAe;IAuCpC,4EAA4E;IAC5E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;IAI7B,wDAAwD;IACxD,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;CAG9B"}

package/dist/client.js

@@ -0,0 +1,65 @@
+import { ScrapyIOError } from './errors.js';
+import { createPlatformClient } from './generated/client.js';
+import { createRetryFetch } from './http.js';
+import { ToolHandle } from './tool.js';
+import { ToolsResource } from './tools.js';
+import { RunsResource } from './runs.js';
+import { RunHandle } from './run.js';
+import { SchedulesResource } from './schedules.js';
+const DEFAULT_BASE_URL = 'https://api.scrapy.io/v1';
+/**
+ * Official Scrapy.io TypeScript SDK.
+ *
+ * API keys must stay server-side. Do not embed keys in browser apps.
+ */
+export class ScrapyIO {
+    tools;
+    runs;
+    schedules;
+    apiKey;
+    platform;
+    fetchImpl;
+    constructor(options) {
+        const apiKey = options.apiKey?.trim();
+        if (!apiKey) {
+            throw new ScrapyIOError({
+                message: 'ScrapyIO requires an apiKey (e.g. process.env.SCRAPYIO_API_KEY)',
+                type: 'sdk_error',
+            });
+        }
+        this.apiKey = apiKey;
+        const baseFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        if (typeof baseFetch !== 'function') {
+            throw new ScrapyIOError({
+                message: 'ScrapyIO requires a fetch implementation (Node 18+ recommended)',
+                type: 'sdk_error',
+            });
+        }
+        this.fetchImpl = createRetryFetch({
+            fetchImpl: baseFetch,
+            maxRetries: options.maxRetries ?? 2,
+            retryBackoffMs: options.retryBackoffMs ?? 250,
+        });
+        const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.platform = createPlatformClient({
+            baseUrl,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                Accept: 'application/json',
+            },
+            fetch: this.fetchImpl,
+        });
+        this.tools = new ToolsResource(this.platform);
+        this.runs = new RunsResource(this.platform);
+        this.schedules = new SchedulesResource(this.platform);
+    }
+    /** Lightweight tool handle (`publisher/slug`). Does not hit the network. */
+    tool(ref) {
+        return new ToolHandle(this.platform, { apiKey: this.apiKey, fetchImpl: this.fetchImpl }, ref);
+    }
+    /** Lightweight run handle. Does not hit the network. */
+    run(runId) {
+        return new RunHandle(this.platform, runId);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAuB,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnD,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD;;;;GAIG;AACH,MAAM,OAAO,QAAQ;IACV,KAAK,CAAgB;IACrB,IAAI,CAAe;IACnB,SAAS,CAAoB;IAErB,MAAM,CAAS;IACf,QAAQ,CAAiB;IACzB,SAAS,CAA0B;IAEpD,YAAY,OAAwB;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;QACtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,aAAa,CAAC;gBACtB,OAAO,EAAE,iEAAiE;gBAC1E,IAAI,EAAE,WAAW;aAClB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrE,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;YACpC,MAAM,IAAI,aAAa,CAAC;gBACtB,OAAO,EAAE,iEAAiE;gBAC1E,IAAI,EAAE,WAAW;aAClB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,gBAAgB,CAAC;YAChC,SAAS,EAAE,SAAS;YACpB,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC;YACnC,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,GAAG;SAC9C,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,QAAQ,GAAG,oBAAoB,CAAC;YACnC,OAAO;YACP,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;gBACtC,MAAM,EAAE,kBAAkB;aAC3B;YACD,KAAK,EAAE,IAAI,CAAC,SAAS;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,SAAS,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC,GAAW;QACd,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,GAAG,CAAC,CAAC;IAChG,CAAC;IAED,wDAAwD;IACxD,GAAG,CAAC,KAAa;QACf,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+export type JsonObject = Record<string, unknown>;
+export type PlatformErrorType = 'unauthorized' | 'forbidden' | 'not_found' | 'validation_error' | 'insufficient_credits' | 'conflict' | 'rate_limit_exceeded' | 'internal_error' | 'timeout' | 'publisher_error' | 'sdk_error';
+export declare class ScrapyIOError extends Error {
+    readonly name = "ScrapyIOError";
+    readonly status: number | undefined;
+    readonly type: PlatformErrorType;
+    readonly docUrl: string | undefined;
+    readonly body: unknown;
+    constructor(options: {
+        message: string;
+        type?: PlatformErrorType;
+        status?: number;
+        docUrl?: string;
+        body?: unknown;
+        cause?: unknown;
+    });
+}
+export declare function isPlatformErrorType(value: string): value is PlatformErrorType;
+export declare function errorFromPlatformBody(status: number, body: unknown, fallbackMessage?: string): ScrapyIOError;
+export declare function errorFromPublisherBody(status: number, body: unknown, fallbackMessage?: string): ScrapyIOError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,WAAW,GACX,WAAW,GACX,kBAAkB,GAClB,sBAAsB,GACtB,UAAU,GACV,qBAAqB,GACrB,gBAAgB,GAChB,SAAS,GACT,iBAAiB,GACjB,WAAW,CAAC;AAEhB,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,OAAO,EAAE;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,iBAAiB,CAAC;QACzB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAOF;AAqBD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,eAAe,SAAgC,GAC9C,aAAa,CAoBf;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,eAAe,SAAuC,GACrD,aAAa,CA8Cf"}

package/dist/errors.js

@@ -0,0 +1,93 @@
+export class ScrapyIOError extends Error {
+    name = 'ScrapyIOError';
+    status;
+    type;
+    docUrl;
+    body;
+    constructor(options) {
+        super(options.message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.type = options.type ?? 'sdk_error';
+        this.status = options.status;
+        this.docUrl = options.docUrl;
+        this.body = options.body;
+    }
+}
+const PLATFORM_ERROR_TYPES = new Set([
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'validation_error',
+    'insufficient_credits',
+    'conflict',
+    'rate_limit_exceeded',
+    'internal_error',
+]);
+export function isPlatformErrorType(value) {
+    return PLATFORM_ERROR_TYPES.has(value);
+}
+export function errorFromPlatformBody(status, body, fallbackMessage = 'Platform API request failed') {
+    const parsed = body;
+    const err = parsed?.error;
+    if (err && typeof err === 'object') {
+        const typeRaw = typeof err.type === 'string' ? err.type : 'internal_error';
+        const type = isPlatformErrorType(typeRaw) ? typeRaw : 'internal_error';
+        return new ScrapyIOError({
+            message: typeof err.message === 'string' && err.message ? err.message : fallbackMessage,
+            type,
+            status,
+            docUrl: typeof err.doc_url === 'string' ? err.doc_url : undefined,
+            body,
+        });
+    }
+    return new ScrapyIOError({
+        message: fallbackMessage,
+        type: status === 401 ? 'unauthorized' : 'internal_error',
+        status,
+        body,
+    });
+}
+export function errorFromPublisherBody(status, body, fallbackMessage = 'Publisher execution request failed') {
+    if (body && typeof body === 'object') {
+        const record = body;
+        if (record.error === 'INSUFFICIENT_CREDITS') {
+            return new ScrapyIOError({
+                message: typeof record.message === 'string' && record.message
+                    ? record.message
+                    : 'Insufficient credits',
+                type: 'insufficient_credits',
+                status: status || 402,
+                body,
+            });
+        }
+        if (typeof record.error === 'string' && record.error) {
+            const message = typeof record.message === 'string' && record.message
+                ? `${record.error}: ${record.message}`
+                : record.error;
+            const type = status === 401
+                ? 'unauthorized'
+                : status === 404
+                    ? 'not_found'
+                    : status === 400
+                        ? 'validation_error'
+                        : status === 409
+                            ? 'conflict'
+                            : 'publisher_error';
+            return new ScrapyIOError({ message, type, status, body });
+        }
+        if (record.success === false && typeof record.error === 'string') {
+            return new ScrapyIOError({
+                message: record.error,
+                type: status === 401 ? 'unauthorized' : 'publisher_error',
+                status,
+                body,
+            });
+        }
+    }
+    return new ScrapyIOError({
+        message: fallbackMessage,
+        type: 'publisher_error',
+        status,
+        body,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,GAAG,eAAe,CAAC;IACvB,MAAM,CAAqB;IAC3B,IAAI,CAAoB;IACxB,MAAM,CAAqB;IAC3B,IAAI,CAAU;IAEvB,YAAY,OAOX;QACC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC3F,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAUD,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAS;IAC3C,cAAc;IACd,WAAW;IACX,WAAW;IACX,kBAAkB;IAClB,sBAAsB;IACtB,UAAU;IACV,qBAAqB;IACrB,gBAAgB;CACjB,CAAC,CAAC;AAEH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,IAAa,EACb,eAAe,GAAG,6BAA6B;IAE/C,MAAM,MAAM,GAAG,IAAgC,CAAC;IAChD,MAAM,GAAG,GAAG,MAAM,EAAE,KAAK,CAAC;IAC1B,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;QAC3E,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC;QACvE,OAAO,IAAI,aAAa,CAAC;YACvB,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;YACvF,IAAI;YACJ,MAAM;YACN,MAAM,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YACjE,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,aAAa,CAAC;QACvB,OAAO,EAAE,eAAe;QACxB,IAAI,EAAE,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB;QACxD,MAAM;QACN,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,IAAa,EACb,eAAe,GAAG,oCAAoC;IAEtD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,IAA+B,CAAC;QAC/C,IAAI,MAAM,CAAC,KAAK,KAAK,sBAAsB,EAAE,CAAC;YAC5C,OAAO,IAAI,aAAa,CAAC;gBACvB,OAAO,EACL,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO;oBAClD,CAAC,CAAC,MAAM,CAAC,OAAO;oBAChB,CAAC,CAAC,sBAAsB;gBAC5B,IAAI,EAAE,sBAAsB;gBAC5B,MAAM,EAAE,MAAM,IAAI,GAAG;gBACrB,IAAI;aACL,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACrD,MAAM,OAAO,GACX,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO;gBAClD,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,OAAO,EAAE;gBACtC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;YACnB,MAAM,IAAI,GACR,MAAM,KAAK,GAAG;gBACZ,CAAC,CAAC,cAAc;gBAChB,CAAC,CAAC,MAAM,KAAK,GAAG;oBACd,CAAC,CAAC,WAAW;oBACb,CAAC,CAAC,MAAM,KAAK,GAAG;wBACd,CAAC,CAAC,kBAAkB;wBACpB,CAAC,CAAC,MAAM,KAAK,GAAG;4BACd,CAAC,CAAC,UAAU;4BACZ,CAAC,CAAC,iBAAiB,CAAC;YAC9B,OAAO,IAAI,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACjE,OAAO,IAAI,aAAa,CAAC;gBACvB,OAAO,EAAE,MAAM,CAAC,KAAK;gBACrB,IAAI,EAAE,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,iBAAiB;gBACzD,MAAM;gBACN,IAAI;aACL,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,IAAI,aAAa,CAAC;QACvB,OAAO,EAAE,eAAe;QACxB,IAAI,EAAE,iBAAiB;QACvB,MAAM;QACN,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/dist/execution.d.ts

@@ -0,0 +1,15 @@
+import type { JsonObject, Run, ToolExecution } from './types.js';
+export type ExecutionContext = {
+    apiKey: string;
+    fetchImpl: typeof globalThis.fetch;
+};
+/**
+ * POST tool-native JSON to publisher `/v1/api` (sync).
+ * Returns the publisher `data` payload on success.
+ */
+export declare function executeCall(ctx: ExecutionContext, execution: ToolExecution, input: JsonObject): Promise<unknown>;
+/**
+ * POST to publisher `/v1/scraper` (async). Maps `taskId` → public `Run.id`.
+ */
+export declare function executeStart(ctx: ExecutionContext, execution: ToolExecution, input: JsonObject): Promise<Run>;
+//# sourceMappingURL=execution.d.ts.map

package/dist/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACpC,CAAC;AAaF;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,OAAO,CAAC,CAiBlB;AA0BD;;GAEG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,GAAG,CAAC,CA4Cd"}

package/dist/execution.js

@@ -0,0 +1,117 @@
+import { errorFromPublisherBody, ScrapyIOError } from './errors.js';
+/**
+ * POST tool-native JSON to publisher `/v1/api` (sync).
+ * Returns the publisher `data` payload on success.
+ */
+export async function executeCall(ctx, execution, input) {
+    const response = await ctx.fetchImpl(execution.apiUrl, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${ctx.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify(input),
+    });
+    const body = await readJsonSafe(response);
+    if (!response.ok) {
+        throw errorFromPublisherBody(response.status, body);
+    }
+    return unwrapPublisherSuccess(body);
+}
+/**
+ * Publisher sync responses use `{ success, data }`. Some tools nest this twice.
+ * Unwrap while the value is a successful envelope (bounded depth).
+ */
+function unwrapPublisherSuccess(body) {
+    let current = body;
+    for (let depth = 0; depth < 4; depth++) {
+        if (!current || typeof current !== 'object' || Array.isArray(current)) {
+            return current;
+        }
+        if (!('success' in current)) {
+            return current;
+        }
+        const record = current;
+        if (record.success === false) {
+            throw errorFromPublisherBody(400, current);
+        }
+        if (record.success !== true) {
+            return current;
+        }
+        current = record.data;
+    }
+    return current;
+}
+/**
+ * POST to publisher `/v1/scraper` (async). Maps `taskId` → public `Run.id`.
+ */
+export async function executeStart(ctx, execution, input) {
+    const response = await ctx.fetchImpl(execution.scraperUrl, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${ctx.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify(input),
+    });
+    const body = await readJsonSafe(response);
+    if (!response.ok) {
+        throw errorFromPublisherBody(response.status, body);
+    }
+    const start = body;
+    if (!start || typeof start.taskId !== 'string' || !start.taskId) {
+        throw new ScrapyIOError({
+            message: 'Publisher did not return a taskId',
+            type: 'publisher_error',
+            status: response.status,
+            body,
+        });
+    }
+    const status = normalizePublisherStatus(start.status);
+    return {
+        id: start.taskId,
+        kind: 'async_batch',
+        status,
+        toolId: '',
+        runName: start.runName ?? null,
+        totalItems: start.totalItems ?? null,
+        processedItems: start.processedItems ?? null,
+        completedItems: start.completedItems ?? null,
+        failedItems: start.failedItems ?? null,
+        estimatedCost: start.estimatedCost ?? null,
+        billedAmount: null,
+        publisher: null,
+        toolSlug: null,
+        createdAt: new Date().toISOString(),
+        completedAt: null,
+    };
+}
+function normalizePublisherStatus(raw) {
+    if (!raw)
+        return 'queued';
+    if (raw === 'completed')
+        return 'succeeded';
+    if (raw === 'queued' ||
+        raw === 'running' ||
+        raw === 'succeeded' ||
+        raw === 'failed' ||
+        raw === 'cancelled' ||
+        raw === 'partial') {
+        return raw;
+    }
+    return 'queued';
+}
+async function readJsonSafe(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"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"}

package/dist/generated/client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AUTO-GENERATED — do not edit by hand.
+ * Re-run: npm run generate
+ */
+import createClient from "openapi-fetch";
+import type { paths } from "./schema.js";
+export type { paths };
+export { createClient };
+export type PlatformClient = ReturnType<typeof createClient<paths>>;
+export declare function createPlatformClient(options: {
+    baseUrl: string;
+    headers?: Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+}): PlatformClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/generated/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/generated/client.ts"],"names":[],"mappings":"AACA;;;GAGG;AACH,OAAO,YAAY,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,YAAY,EAAE,KAAK,EAAE,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAEpE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC,GAAG,cAAc,CAMjB"}

package/dist/generated/client.js

@@ -0,0 +1,15 @@
+/* eslint-disable */
+/**
+ * AUTO-GENERATED — do not edit by hand.
+ * Re-run: npm run generate
+ */
+import createClient from "openapi-fetch";
+export { createClient };
+export function createPlatformClient(options) {
+    return createClient({
+        baseUrl: options.baseUrl,
+        headers: options.headers,
+        fetch: options.fetch,
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/generated/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/generated/client.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;GAGG;AACH,OAAO,YAAY,MAAM,eAAe,CAAC;AAIzC,OAAO,EAAE,YAAY,EAAE,CAAC;AAIxB,MAAM,UAAU,oBAAoB,CAAC,OAIpC;IACC,OAAO,YAAY,CAAQ;QACzB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC;AACL,CAAC"}