@oomol-lab/open-connector 1.8.0 → 1.9.0

package/src/providers/clay/actions.js

@@ -0,0 +1,222 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+import { clayBatchActions } from "./batch-actions.js";
+import { tableQueryInput } from "./table-schema.js";
+const empty = s.requiredObject("No parameters.", {});
+const reference = s.object("Query reference.", {
+    reference: s.string("Query grammar and field catalog in Markdown."),
+}, {
+    required: ["reference"],
+    additionalProperties: true,
+});
+const routineId = s.string("Routine ID, such as function:t_abc123.", {
+    minLength: 1,
+    maxLength: 64,
+});
+const runId = s.string("Routine run ID.", { minLength: 1, maxLength: 64 });
+const cursor = s.string("Opaque cursor returned by the previous page.");
+const pageLimit = s.integer("Maximum results per page, from 1 to 100.", {
+    minimum: 1,
+    maximum: 100,
+});
+const runOutput = s.object("Routine run progress and results. A complete run may contain failed items.", {
+    routine_run_id: runId,
+    status: s.string("Run status; in_progress or complete. Preserve unknown terminal statuses."),
+    total: s.number("Total input items in the run."),
+    finished: s.number("Finished items, including failures."),
+    data: s.array("Results on this page; absent while running.", s.object("One item result.", {
+        id: s.string("Caller-supplied item ID."),
+        status: s.string("Item status, complete or failed."),
+        result: s.looseObject("Function-defined output fields."),
+        error: s.looseObject("Item failure details.", { message: s.string("Failure message.") }),
+    }, {
+        required: ["id", "status"],
+        additionalProperties: true,
+    })),
+    cursor,
+}, {
+    required: ["routine_run_id", "status"],
+    additionalProperties: true,
+});
+export const clayActions = [
+    ...clayBatchActions,
+    defineProviderAction("clay", {
+        name: "get_me",
+        operationType: "read",
+        description: "Get the Clay user and workspace associated with the API key.",
+        inputSchema: empty,
+        outputSchema: s.object("Authenticated identity.", {
+            user: s.object("Clay user.", {
+                id: s.string("User ID."),
+                name: s.nullable(s.string("User name.")),
+                email: s.nullable(s.string("User email.")),
+                cli_onboarded: s.boolean("Whether CLI onboarding is complete."),
+            }, {
+                required: ["id", "name"],
+                additionalProperties: true,
+            }),
+            workspace: s.object("Clay workspace.", {
+                id: s.string("Workspace ID."),
+                name: s.nullable(s.string("Workspace name.")),
+            }, {
+                required: ["id"],
+                additionalProperties: true,
+            }),
+        }, {
+            required: ["user", "workspace"],
+            additionalProperties: true,
+        }),
+    }),
+    defineProviderAction("clay", {
+        name: "get_credit_balance",
+        operationType: "read",
+        description: "Get workspace credit balances without consuming credits.",
+        inputSchema: empty,
+        outputSchema: s.object("Workspace credit balances.", {
+            balance: s.number("Remaining spendable data credits, including rollover."),
+            action_execution_balance: s.number("Remaining actions; absent on some billing plans."),
+        }, {
+            required: ["balance"],
+            additionalProperties: true,
+        }),
+    }),
+    defineProviderAction("clay", {
+        name: "get_search_query_reference",
+        operationType: "read",
+        description: "Get the current Clay search query grammar and fields before creating a search.",
+        inputSchema: empty,
+        outputSchema: reference,
+    }),
+    defineProviderAction("clay", {
+        name: "create_search",
+        operationType: "write",
+        description: "Create a stateful company or people search from a Clay query. Count-mode and jobs queries are unsupported.",
+        inputSchema: s.requiredObject("Search creation parameters.", {
+            query: s.nonEmptyString("Clay advanced search query; obtain grammar with get_search_query_reference."),
+        }),
+        outputSchema: s.object("Created search iterator.", {
+            search_id: s.string("Search ID to pass to get_search_results."),
+            source_type: s.string("Detected source type, people or companies."),
+        }, {
+            required: ["search_id", "source_type"],
+            additionalProperties: true,
+        }),
+    }),
+    defineProviderAction("clay", {
+        name: "get_search_results",
+        operationType: "write",
+        description: "Fetch the next page and advance a Clay search iterator. Do not retry blindly: each call advances the iterator.",
+        inputSchema: s.object("Search page parameters.", {
+            search_id: s.nonEmptyString("Search ID returned by create_search."),
+            limit: s.integer("Page size, 1–500; default 20. Free and trial plans allow at most 50.", {
+                minimum: 1,
+                maximum: 500,
+            }),
+        }, {
+            optional: ["limit"],
+        }),
+        outputSchema: s.object("Search page.", {
+            data: s.array("Company or people records.", s.looseObject("Search record with upstream fields.")),
+            has_more: s.boolean("Whether more results can be fetched."),
+            source_type: s.string("Source type, people or companies."),
+            exhaustion_reason: s.string("Why results ended: query_limit or no_more_results."),
+            period_quota: s.looseObject("Search quota for the current period.", {
+                limit: s.number("Period quota limit."),
+                used: s.number("Results used in this period."),
+                remaining: s.number("Remaining results in this period."),
+                resets_at: s.string("Quota reset time."),
+            }),
+        }, {
+            required: ["data", "has_more", "source_type"],
+            additionalProperties: true,
+        }),
+    }),
+    defineProviderAction("clay", {
+        name: "run_routine",
+        operationType: "destructive",
+        description: "Run a configured Clay routine on 1–100 items asynchronously. The routine may perform arbitrary downstream mutations; inspect its definition before running.",
+        inputSchema: s.object("Routine execution parameters.", {
+            routine_id: routineId,
+            items: s.array("Items to process.", s.requiredObject("One input item.", {
+                id: s.string("Caller-supplied item ID for matching results.", {
+                    minLength: 1,
+                    maxLength: 64,
+                }),
+                inputs: s.looseObject("Function-defined input fields."),
+            }), { minItems: 1, maxItems: 100 }),
+            webhook_id: s.string("ID of an existing Clay webhook to notify on completion.", {
+                minLength: 1,
+                maxLength: 64,
+            }),
+        }, {
+            optional: ["webhook_id"],
+        }),
+        outputSchema: s.object("Submitted routine run.", { routine_run_id: runId, status: s.string("Initial run status, in_progress.") }, {
+            required: ["routine_run_id", "status"],
+            additionalProperties: true,
+        }),
+        asyncLifecycle: {
+            startActionId: "clay.run_routine",
+            statusActionId: "clay.get_routine_results",
+        },
+    }),
+    defineProviderAction("clay", {
+        name: "get_routine_results",
+        operationType: "read",
+        description: "Get routine progress or one page of completed results. Follow cursor until absent and check each item's status.",
+        inputSchema: s.object("Routine result parameters.", { routine_run_id: runId, cursor, limit: pageLimit }, {
+            optional: ["cursor", "limit"],
+        }),
+        outputSchema: runOutput,
+        asyncLifecycle: {
+            startActionId: "clay.run_routine",
+            statusActionId: "clay.get_routine_results",
+        },
+    }),
+    defineProviderAction("clay", {
+        name: "query_tables",
+        operationType: "read",
+        description: "Query known Clay tables on Enterprise plans. Concurrent updates can repeat rows; deduplicate by ID. Custom ordering and aggregation do not support cursor pagination.",
+        inputSchema: tableQueryInput,
+        outputSchema: s.object("Table query results.", {
+            data: s.array("Rows keyed by selected field; cells include status and value.", s.looseObject("Row of cell results.")),
+            fields: s.looseObject("Field metadata keyed by output column."),
+            cursor,
+            truncated: s.boolean("More rows matched but this query cannot issue a cursor; narrow the query or increase the limit."),
+        }, {
+            required: ["data"],
+            additionalProperties: true,
+        }),
+    }),
+    defineProviderAction("clay", {
+        name: "get_workflow_run_query_reference",
+        operationType: "read",
+        description: "Get the workflow-run query grammar and supported fields (beta).",
+        inputSchema: empty,
+        outputSchema: reference,
+    }),
+    defineProviderAction("clay", {
+        name: "query_workflow_runs",
+        operationType: "read",
+        description: "Search or count workflow runs (beta). Results are eventually consistent; recently changed runs may be stale or absent.",
+        inputSchema: s.object("Workflow-run query parameters.", {
+            query: s.string("Clay workflow-run select or count query.", {
+                minLength: 1,
+                maxLength: 2000,
+            }),
+            cursor,
+            limit: pageLimit,
+        }, {
+            optional: ["cursor", "limit"],
+        }),
+        outputSchema: s.object("Workflow-run query result.", {
+            mode: s.string("Query mode, select or count."),
+            count: s.integer("Number of matching runs for count mode.", { minimum: 0 }),
+            data: s.array("Matching runs in newest-first order for select mode.", s.looseObject("Workflow run metadata.")),
+            cursor,
+        }, {
+            required: ["mode"],
+            additionalProperties: true,
+        }),
+    }),
+];

package/src/providers/clay/batch-actions.d.ts

@@ -0,0 +1,2 @@
+import type { ActionDefinition } from "../../core/types.ts";
+export declare const clayBatchActions: ActionDefinition[];

package/src/providers/clay/batch-actions.js

@@ -0,0 +1,71 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+const runId = s.string("Batch routine run ID.", { minLength: 1, maxLength: 64 });
+export const clayBatchActions = [
+    defineProviderAction("clay", {
+        name: "run_routine_batch",
+        operationType: "destructive",
+        description: "Download a JSONL file, upload it to Clay, and start an asynchronous batch routine. Each line must contain id and inputs. The routine may perform arbitrary downstream mutations. Requires streaming transit storage. Transfer limit: the lower of 2 GiB and the configured transit storage limit, five minutes each for download and upload; JSONL validation is performed by Clay.",
+        inputSchema: s.object("Batch routine submission parameters.", {
+            routine_id: s.string("Routine ID, such as function:t_abc123.", {
+                minLength: 1,
+                maxLength: 64,
+            }),
+            fileUrl: s.string("Public HTTP(S) URL of a UTF-8 JSONL file; signed URLs are supported. The connector downloads it without Clay credentials.", { format: "uri", minLength: 1 }),
+            webhook_id: s.string("ID of an existing Clay webhook to notify on completion.", {
+                minLength: 1,
+                maxLength: 64,
+            }),
+        }, {
+            optional: ["webhook_id"],
+        }),
+        outputSchema: s.object("Submitted batch routine run.", {
+            routine_run_id: runId,
+            status: s.string("Initial run status, in_progress."),
+        }, {
+            required: ["routine_run_id", "status"],
+            additionalProperties: true,
+        }),
+        asyncLifecycle: {
+            startActionId: "clay.run_routine_batch",
+            statusActionId: "clay.get_routine_batch_results",
+        },
+    }),
+    defineProviderAction("clay", {
+        name: "get_routine_batch_results",
+        operationType: "read",
+        description: "Get batch progress, a result download URL, or validation/processing failure details. Download result_url separately after completion and inspect individual item outcomes; results are not loaded into the action response.",
+        inputSchema: s.requiredObject("Batch result parameters.", { routine_run_id: runId }),
+        outputSchema: s.object("Batch progress or terminal outcome.", {
+            routine_run_id: runId,
+            status: s.string("Batch status: in_progress, complete, validation_failed, or processing_failed; unknown statuses are preserved."),
+            total: s.number("Total input items, when available."),
+            finished: s.number("Finished items, including failures, when available."),
+            result_url: s.string("Result file download URL returned on completion; may contain a signed access token.", {
+                format: "uri",
+            }),
+            error: s.object("Batch validation or processing error.", {
+                message: s.string("Failure message."),
+                total_invalid_rows: s.number("Total invalid JSONL rows for validation failures."),
+                details: s.array("Validation errors reported by Clay, up to 100 entries.", s.object("One JSONL validation error.", {
+                    field: s.string("Invalid field."),
+                    line_number: s.number("JSONL line number."),
+                    message: s.string("Validation error message."),
+                }, {
+                    required: ["field", "line_number", "message"],
+                    additionalProperties: true,
+                })),
+            }, {
+                required: ["message"],
+                additionalProperties: true,
+            }),
+        }, {
+            required: ["routine_run_id", "status"],
+            additionalProperties: true,
+        }),
+        asyncLifecycle: {
+            startActionId: "clay.run_routine_batch",
+            statusActionId: "clay.get_routine_batch_results",
+        },
+    }),
+];

package/src/providers/clay/batch-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { ApiKeyProviderContext } from "../provider-runtime.ts";
+export declare function runClayBatch(context: ApiKeyProviderContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;

package/src/providers/clay/batch-runtime.js

@@ -0,0 +1,79 @@
+import { optionalRawString } from "../../core/cast.js";
+import { createProviderFetch, providerInputError, ProviderRequestError, providerResponseError, runProviderRequest, } from "../provider-runtime.js";
+import { encodeSegment, requestClay } from "./request.js";
+const maximumBatchBytes = 2 * 1024 * 1024 * 1024;
+export async function runClayBatch(context, input) {
+    const store = context.transitFiles;
+    if (!store?.createFromStream || !store.response)
+        throw providerInputError("Clay batch upload requires streaming transit storage");
+    const fetcher = createProviderFetch({ fetch: context.fetcher });
+    const routinePath = `/routines/${encodeSegment(input.routine_id)}/run-batch`;
+    const stored = await runProviderRequest({ label: "Clay batch download", signal: context.signal, timeoutMs: 300_000 }, async (signal) => {
+        const response = await fetcher(String(input.fileUrl), { signal });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new ProviderRequestError(response.status, `Clay batch file download failed (HTTP ${response.status})`, undefined, "provider_error");
+        }
+        if (!response.body)
+            throw providerInputError("Clay batch file is empty");
+        const limit = Math.min(maximumBatchBytes, store.maxBytes);
+        if (Number(response.headers.get("content-length")) > limit) {
+            await response.body.cancel();
+            throw new ProviderRequestError(413, "Clay batch file exceeds the configured transfer limit");
+        }
+        let size = 0;
+        const body = response.body.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                size += chunk.byteLength;
+                if (size > limit)
+                    throw new ProviderRequestError(413, "Clay batch file exceeds the configured transfer limit");
+                controller.enqueue(chunk);
+            },
+            flush() {
+                if (size === 0)
+                    throw providerInputError("Clay batch file is empty");
+            },
+        }));
+        return store.createFromStream({ body, name: "input.jsonl", mimeType: "application/x-ndjson", signal });
+    });
+    const { fileId } = stored;
+    try {
+        const upload = await requestClay(context, `${routinePath}/upload-url`, undefined, "POST");
+        const uploadUrl = optionalRawString(upload.upload_url);
+        const upstreamFileId = optionalRawString(upload.file_id);
+        if (!uploadUrl || !upstreamFileId)
+            throw providerResponseError("Clay batch upload response is missing upload_url or file_id");
+        if (new URL(uploadUrl).protocol !== "https:")
+            throw providerResponseError("Clay upload_url must use HTTPS");
+        await runProviderRequest({ label: "Clay batch upload", signal: context.signal, timeoutMs: 300_000 }, async (signal) => {
+            const staged = await store.response(fileId);
+            if (!staged.body)
+                throw providerResponseError("Clay staged file has no body");
+            const options = {
+                method: "PUT",
+                body: staged.body,
+                duplex: "half",
+                signal,
+                redirect: "manual",
+                headers: { "content-type": "application/x-ndjson", "content-length": String(stored.sizeBytes) },
+            };
+            try {
+                const response = await fetcher(uploadUrl, options);
+                await response.body?.cancel();
+                if (!response.ok)
+                    throw new ProviderRequestError(response.status, `Clay batch file upload failed (HTTP ${response.status})`, undefined, "provider_error");
+            }
+            finally {
+                if (!staged.body.locked)
+                    await staged.body.cancel().catch(() => { });
+            }
+        });
+        return await requestClay(context, `${routinePath}/start`, {
+            file_id: upstreamFileId,
+            webhook_id: input.webhook_id,
+        });
+    }
+    finally {
+        await store.delete(fileId);
+    }
+}

package/src/providers/clay/executors.d.ts

@@ -0,0 +1,4 @@
+import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+export declare const executors: ProviderExecutors;
+export declare const credentialValidators: CredentialValidators;
+export declare const proxy: ProviderProxyExecutor;

package/src/providers/clay/executors.js

@@ -0,0 +1,78 @@
+import { optionalRawString } from "../../core/cast.js";
+import { defineApiKeyProviderExecutors, defineProviderProxy, mapProviderActionHandlers, requiredInputString, requiredResponseRecord, providerUserAgent, } from "../provider-runtime.js";
+import { clayActions } from "./actions.js";
+import { runClayBatch } from "./batch-runtime.js";
+import { baseUrl, encodeSegment, requestClay } from "./request.js";
+const readPaths = {
+    get_me: "/me",
+    get_credit_balance: "/credits/balance",
+    get_search_query_reference: "/search/query-mode/reference",
+    get_workflow_run_query_reference: "/workflows/runs/query/reference",
+};
+const handlers = mapProviderActionHandlers("clay", clayActions, (action) => async (values, context) => {
+    const body = values;
+    switch (action.name) {
+        case "get_me":
+        case "get_credit_balance":
+        case "get_search_query_reference":
+        case "get_workflow_run_query_reference":
+            return requestClay(context, readPaths[action.name]);
+        case "create_search":
+            return requestClay(context, "/search/query-mode", body);
+        case "get_search_results": {
+            const { search_id, ...page } = body;
+            return requestClay(context, `/search/query-mode/${encodeSegment(search_id)}/run`, page);
+        }
+        case "run_routine": {
+            const { routine_id, ...run } = body;
+            return requestClay(context, `/routines/${encodeSegment(routine_id)}/run`, run);
+        }
+        case "get_routine_results": {
+            const { routine_run_id, cursor, limit } = body;
+            const query = new URLSearchParams();
+            if (cursor !== undefined)
+                query.set("cursor", String(cursor));
+            if (limit !== undefined)
+                query.set("limit", String(limit));
+            return requestClay(context, `/routines/run/${encodeSegment(routine_run_id)}/results?${query}`);
+        }
+        case "run_routine_batch":
+            return runClayBatch(context, body);
+        case "get_routine_batch_results":
+            return requestClay(context, `/routines/run-batch/${encodeSegment(body.routine_run_id)}/results`);
+        case "query_tables":
+            return requestClay(context, "/tables/query", body);
+        case "query_workflow_runs":
+            return requestClay(context, "/workflows/runs/query", body);
+    }
+});
+export const executors = defineApiKeyProviderExecutors("clay", handlers, {
+    skipDnsValidation: false,
+});
+export const credentialValidators = {
+    async apiKey(input, { fetcher, signal }) {
+        const payload = await requestClay({ apiKey: requiredInputString(input.apiKey, "API Key"), fetcher, signal }, "/me");
+        const workspace = requiredResponseRecord(payload.workspace, "Clay workspace");
+        const user = requiredResponseRecord(payload.user, "Clay user");
+        return {
+            profile: { displayName: optionalRawString(workspace.name) ?? optionalRawString(user.name) ?? "Clay API Key" },
+            grantedScopes: [],
+            metadata: { workspaceId: optionalRawString(workspace.id), apiBaseUrl: baseUrl },
+        };
+    },
+};
+export const proxy = defineProviderProxy({
+    service: "clay",
+    baseUrl,
+    auth: { type: "api_key_header", name: "clay-api-key" },
+    skipDnsValidation: true,
+    customizeRequest({ headers }) {
+        for (const [name, value] of Object.entries({
+            accept: "application/json",
+            "content-type": "application/json",
+            "user-agent": providerUserAgent,
+        }))
+            if (!headers.has(name))
+                headers.set(name, value);
+    },
+});

package/src/providers/clay/request.d.ts

@@ -0,0 +1,4 @@
+import type { ApiKeyProviderContext } from "../provider-runtime.ts";
+export declare const baseUrl = "https://api.clay.com/public/v0";
+export declare function encodeSegment(value: unknown): string;
+export declare function requestClay(context: ApiKeyProviderContext, path: string, body?: Record<string, unknown>, method?: string): Promise<Record<string, unknown>>;

package/src/providers/clay/request.js

@@ -0,0 +1,34 @@
+import { optionalRawString, optionalRecord } from "../../core/cast.js";
+import { providerInputError, ProviderRequestError, providerUserAgent, readProviderJsonBody, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+export const baseUrl = "https://api.clay.com/public/v0";
+export function encodeSegment(value) {
+    const segment = String(value);
+    if (segment === "." || segment === "..")
+        throw providerInputError("Invalid Clay resource ID");
+    return encodeURIComponent(segment);
+}
+export function requestClay(context, path, body, method = body === undefined ? "GET" : "POST") {
+    return runProviderRequest({ label: "Clay", signal: context.signal }, async (signal) => {
+        const response = await context.fetcher(`${baseUrl}${path}`, {
+            method,
+            headers: {
+                "clay-api-key": context.apiKey,
+                accept: "application/json",
+                "content-type": "application/json",
+                "user-agent": providerUserAgent,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal,
+        });
+        const payload = await readProviderJsonBody(response, {
+            emptyBody: null,
+            invalidJsonMessage: "Clay returned invalid JSON",
+            invalidJsonFallback: response.ok ? undefined : () => null,
+        });
+        if (!response.ok) {
+            const message = optionalRawString(optionalRecord(payload)?.message);
+            throw new ProviderRequestError(response.status, message ? `Clay: ${message}` : `Clay request failed (HTTP ${response.status})`, undefined, "provider_error");
+        }
+        return requiredResponseRecord(payload, "Clay");
+    });
+}

package/src/providers/clay/table-schema.d.ts

@@ -0,0 +1,2 @@
+import type { JsonSchema } from "../../core/types.ts";
+export declare const tableQueryInput: JsonSchema;

package/src/providers/clay/table-schema.js

@@ -0,0 +1,102 @@
+import { s } from "../../core/json-schema.js";
+const field = s.nonEmptyString("Field name or ID according to field_mode.");
+const nestedPath = s.array("Nested property path, up to 5 segments.", s.nonEmptyString("Path segment."), {
+    minItems: 1,
+    maxItems: 5,
+});
+const filterRef = { $ref: "#/$defs/filter", description: "Recursive filter expression." };
+const filter = s.anyOf([
+    s.object("Field predicate.", {
+        field,
+        op: s.stringEnum("Comparison operator.", [
+            "=",
+            "!=",
+            ">",
+            ">=",
+            "<",
+            "<=",
+            "contains",
+            "not_contains",
+            "starts_with",
+            "ends_with",
+            "in",
+            "not_in",
+            "is_empty",
+            "is_not_empty",
+        ]),
+        path: nestedPath,
+        value: s.anyOf([
+            s.string("Text value."),
+            s.number("Numeric value."),
+            s.boolean("Boolean value."),
+            s.array("Values for membership tests.", s.anyOf([s.string("Text value."), s.number("Numeric value.")], {
+                description: "Text or number.",
+            })),
+        ], { description: "Comparison value; omit for empty checks." }),
+    }, {
+        optional: ["path", "value"],
+    }),
+    s.requiredObject("All child conditions must match.", {
+        and: s.array("Conjoined conditions.", filterRef, { minItems: 1, maxItems: 10 }),
+    }),
+    s.requiredObject("Any child condition may match.", {
+        or: s.array("Alternative conditions.", filterRef, { minItems: 1, maxItems: 10 }),
+    }),
+    s.requiredObject("Negated condition.", { not: filterRef }),
+], { description: "Predicate or Boolean filter expression." });
+export const tableQueryInput = {
+    ...s.object("Structured table query parameters.", {
+        query: s.object("Structured query over known tables.", {
+            tables: s.array("Tables to query, up to 5.", s.object("Table reference.", {
+                id: s.nonEmptyString("Table ID from the Clay table URL after /tables/."),
+                alias: s.string("Optional table alias."),
+            }, {
+                optional: ["alias"],
+            }), { minItems: 1, maxItems: 5 }),
+            field_mode: s.stringEnum("Whether fields use names or IDs.", ["names", "ids"]),
+            select: s.array("Selected fields or aggregates, up to 20.", s.anyOf([
+                s.object("Aggregate selection.", {
+                    fn: s.stringEnum("Aggregate function.", ["count", "sum", "avg", "max", "min"]),
+                    field,
+                    as: s.nonEmptyString("Output alias for the aggregate."),
+                    path: nestedPath,
+                }, {
+                    optional: ["path"],
+                }),
+                s.object("Field selection.", {
+                    field,
+                    path: nestedPath,
+                    as: s.string("Output column alias."),
+                    table: s.string("Table reference for the field."),
+                }, {
+                    optional: ["path", "as", "table"],
+                }),
+            ], { description: "Field selection or aggregate." }), { maxItems: 20 }),
+            filter: filterRef,
+            group_by: s.array("Grouping fields, up to 5.", field, { maxItems: 5 }),
+            join: s.array("Table joins, up to 4.", s.object("Table join.", {
+                table: s.nonEmptyString("Table reference to join."),
+                type: s.stringEnum("Join type; defaults to inner.", ["inner", "left"]),
+                on: s.requiredObject("Join condition.", {
+                    left: s.nonEmptyString("Left join field."),
+                    right: s.nonEmptyString("Right join field."),
+                }),
+            }, {
+                optional: ["type"],
+            }), { maxItems: 4 }),
+            order_by: s.array("Custom ordering disables cursor pagination; up to 3 fields.", s.object("Sort term.", {
+                field,
+                direction: s.stringEnum("Sort direction; defaults to asc.", ["asc", "desc"]),
+            }, {
+                optional: ["direction"],
+            }), { maxItems: 3 }),
+        }, {
+            optional: ["field_mode", "select", "filter", "group_by", "join", "order_by"],
+        }),
+        cursor: s.string("Opaque cursor; concurrent updates can repeat rows, so deduplicate by ID."),
+        limit: s.integer("Page size, 1–100; defaults to 50.", { minimum: 1, maximum: 100 }),
+    }, {
+        optional: ["cursor", "limit"],
+    }),
+    $defs: { filter },
+};

package/src/providers/cloudflare_r2/runtime.js

@@ -1,5 +1,5 @@
 import { base64Bytes, compactObject, integer, optionalInteger, optionalRecord, optionalString, requiredRawString, requiredString, } from "../../core/cast.js";
-import { assertPublicHttpUrl, queryParams, readBoundedResponseBytes } from "../../core/request.js";
+import { assertPublicHttpUrl, queryParams, readBoundedResponseBytes, storeResponseInTransit, } from "../../core/request.js";
 import { readCloudflareCurrentUser } from "../cloudflare_dns/runtime-user.js";
 import { combineProviderActionHandlers, providerFetch, providerInputError, ProviderRequestError, providerUserAgent, runProviderRequest, } from "../provider-runtime.js";
 import { cloudflareR2AccountActionHandlers } from "./runtime-account.js";
@@ -158,12 +158,13 @@ async function downloadObject(input, context) {
     }
     const name = optionalString(input.fileName) ?? defaultObjectFileName(objectKey);
     const mimeType = optionalString(response.headers.get("content-type")) ?? "application/octet-stream";
-    const bytes = await readBoundedResponseBytes(response, {
-        maxBytes: context.transitFiles.maxBytes,
+    const file = await storeResponseInTransit(response, context.transitFiles, {
+        name,
+        mimeType,
         fieldName: "Cloudflare R2 download",
         createError: (message) => new ProviderRequestError(413, message),
+        signal: context.signal,
     });
-    const file = await context.transitFiles.create(new File([Uint8Array.from(bytes)], name, { type: mimeType }));
     return {
         fileId: objectKey,
         name,

package/src/providers/commonninja/executors.d.ts

@@ -0,0 +1,4 @@
+import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+export declare const executors: ProviderExecutors;
+export declare const credentialValidators: CredentialValidators;
+export declare const proxy: ProviderProxyExecutor;