@zackbart/connecta 0.34.0 → 0.35.0

package/dist/providers/cloudflare/skill.generated.js

@@ -1,13 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "- Resolve account and zone ids before acting; never guess one. Ids are 32-character hex strings, and a zone is found by its domain name. Defaults and pins route a connector; Cloudflare's permissions still decide what the credential may do.\n- Read state before replacing, rolling back, or purging. For DNS, PATCH changes the fields you send and PUT replaces the whole record, so read the record first and send its type, name, and content with the change. Prefer a targeted cache purge (files, tags, hosts, or prefixes) over purging everything.\n- Cloudflare reports failures in `errors` with numeric codes and returns `success: false`; read the message instead of retrying the same call.\n- Honor rate-limit waits. Cloudflare documents 1,200 requests per five minutes per user, counted across the dashboard and every token; Connecta's per-runtime window approximates it, and a limited user is blocked for the rest of the window.\n- Treat every create, update, delete, purge, deploy, and upload as a write. For guest calls, classification, and routing, fetch `skills({ name: \"usage\" })`.\n",
-    "instructionsHeading": "Account instructions",
-    "fragments": {
-        "oauth": "\n\n- The catalog is Cloudflare's own `search` and `execute`. `search` runs code against Cloudflare's OpenAPI document; `execute` runs code that may call any Cloudflare API endpoint the OAuth grant allows.\n- Connecta classifies `execute` as a write, even for a program that only reads, because one program can mix GET, POST, PUT, PATCH, and DELETE and no schema proves otherwise. A read-only endpoint therefore gets only `search` here. Deployments that need API reads from a read-only endpoint configure an API-token connector, whose `cloudflare_api_read` and named reads are reads.\n- Use `search` to find the exact method, path, and fields before writing an execute program. Do not guess an endpoint from product naming.\n- Keep returned values small. Filter and project inside the Cloudflare program, then reduce again inside Connecta's `execute_code` when several calls must be joined.\n- This connection has none of the REST connector's tools: no `cloudflare_api_*` validation against a pinned index, no `graphql_query`, no `cloudflare_api_upload`, and no account or zone pin. OAuth permissions are the boundary.\n",
-        "oauth_tail": "- An `auth_required` failure means this connector's Cloudflare authorization is missing or expired: run `authorize_connector` for this connector id, then retry the same call unchanged.\n",
-        "global_warning": "\n\nThis connector holds a Global API Key. It acts as its Cloudflare user with every permission that user has, in every account and zone the user belongs to, and nothing on Cloudflare's side narrows it. A mistaken write can reach production domains, billing, and members across all of them. Prefer reads, state the account and zone of every write, and stop when a request is ambiguous. Writes under `/user` and `/memberships` are refused. R2 accepts API tokens only, so R2 operations fail with this key.\n",
-        "key": "\n\n- This is Connecta's REST connector to the Cloudflare v4 API, holding one operator-managed credential. `cloudflare_api_search` finds API operations in a pinned index (not records) and names the tool that calls each; `cloudflare_api_details` returns one operation's parameters and body with types, enums, and required names. Neither sends a request.\n- `cloudflare_api_read` calls GET operations plus reviewed read-only POSTs: analytics queries, Analytics Engine and SQL API queries, Log Explorer SQL, Vectorize queries, KV bulk get, telemetry queries, and validation checks. `cloudflare_api_write` calls every other POST, PUT, PATCH, and DELETE with `method` and `path` stated. D1 `…/query` and `…/raw`, Durable Object queries, Workers AI `…/ai/run`, AI Search and AutoRAG search (query rewriting runs billed models), monetization checks, and flag evaluation are writes: they can change data, cost money, or activate something.\n- Paths are concrete: substitute ids into the template search returned (`/zones/<zone id>/dns_records/<record id>`). Pass `query` and `body` as JSON named as details lists them; text operations (Analytics Engine SQL, Log Explorer SQL, Worker scripts) take a string body, and Vectorize inserts a list of objects sent as NDJSON. R2 calls accept `headers` with `cf-r2-jurisdiction` or `cf-r2-storage-class`. Encode a `/` inside an R2 object key or KV key name as `%2F`.\n- Every call is checked against the pinned index before it is sent. An unknown path returns the nearest operations; an unknown or missing parameter returns `validation.issues` with the accepted names. Nothing reached Cloudflare, so fix the call from that answer.\n- Under an account pin, each uncached zone-ownership check also spends the connector's call budget. Checks stay capped at three per call and 60 per five minutes per connector; an exhausted budget stops the check and the requested operation.\n- Results arrive as `{ status, data, page? }` with Cloudflare's envelope unwrapped: `data` is the `result`. On a list, pass `page.next` as the `page.param` query argument (`page` for numbered lists, `cursor` for KV, R2, and other cursor lists). Lists belong inside `execute_code`; pass `select` (dot paths such as `id` and `name`) to keep only the fields the question needs.\n- `list_zones` and `list_accounts` resolve names to ids; `verify_credential` separates a bad credential from a missing permission. `graphql_query` runs read-only GraphQL Analytics queries (mutations are refused before sending); filter every `zones` or `accounts` field by `zoneTag` or `accountTag`. A pinned connector sends one query per document, with every fragment it defines used.\n- Multipart, binary, and file bodies go through `cloudflare_api_upload`: Worker scripts and versions, KV values, R2 objects, Pages deployments, Images, Stream, DNS zone-file import, and Snippets. It takes `textBody`, `base64Body`, or multipart `parts`, never a local file.\n- Refused by design: every operation that mints, rotates, or hands back a credential (API tokens, Access service tokens, R2 temporary credentials, tunnel and Mesh node tokens, signing keys, registry credentials, direct-upload URLs, deploy hooks, preview and participant tokens), payment client secrets, URL Scanner captures (results, HAR, DOM, raw responses: they hold the scanned session's cookies and headers; use the scan search for verdicts), and GETs that act (an email unsubscribe, a PagerDuty connect). Stored and embedded secrets (Turnstile, TSIG, webhook and identity-provider secrets, Stream keys, Logpush destination credentials, probe and custom-provider headers, BGP keys, Zaraz variables, Hyperdrive database passwords, RealtimeKit storage credentials, transform-rule header values) and every environment or plain-text binding value (Pages, Containers, Workers, Builds; names and types stay) come back as `\"[redacted]\"` on every method. Notification, RealtimeKit, and data security webhook destinations keep only their scheme and host. Workers KV values are application data and come back as stored. Reviewed operations, and operations that take credentials, report Cloudflare's error codes without its error text. Worker script content is readable: it is code, and secret bindings are not part of it.\n- An `auth_required` failure means the credential is missing, revoked, or malformed: an operator must replace it in this connection in the operator UI, and `authorize_connector` returns that handoff. `provider_permission_denied` means the credential works but lacks this permission or resource, or the call is outside the pin; ask rather than retry.\n- Embedded URL safety uses reviewed paths plus global signing parameters. Generic credential-named query parameters (`code`, `key`, `token`, `sig`, etc.) and credential-looking fragments withhold the destination's entire query/fragment only in Workers build `lines`, Pages log `data.line`, and telemetry `$metadata.message`/`error` and raw string/object `source` payloads in both `events.events` and `invocations.*` on the reviewed log operations and vendor error text. Ordinary `code`/`key` links can therefore be false positives in these diagnostics. DNS TXT content, KV values, Access/Waiting Room custom HTML and other operator content keep those ordinary URL parameters byte for byte. Literal AWS SigV4/Google V4 `X-Amz-*`/`X-Goog-*` Signature, Credential and Security-Token values are withheld in every decoded string before projection. A withheld value is not the original: do not write it back. KV bulk writes also inspect decoded `value` fields with `base64: true` (up to Cloudflare's 25 MiB decoded value limit; malformed or oversized base64 is refused, and the host's inbound body cap still applies). All writes, including named writes and supported raw/base64/multipart uploads, reject URL destinations whose own query/fragment contains the exact `[redacted]` placeholder, plain or encoded, with `invalid_args` before dispatch. Admission iteratively checks every JSON key and value within the host's accepted request size, without separate depth or node-count ceilings; cyclic direct arguments are refused. A marker outside the destination remains ordinary text. Split strings, encoded host/signing names, bare hosts without `//`, and opaque bearer paths remain outside this scan. Binary responses represented as base64, including Worker JavaScript served as `application/javascript`, are returned unchanged and are not decoded/scanned. An envelope cursor that would change under URL sanitizing is omitted rather than echoed or reused.\n",
-        "shared": "- Resolve account and zone ids before acting; never guess one. Ids are 32-character hex strings, and a zone is found by its domain name. Defaults and pins route a connector; Cloudflare's permissions still decide what the credential may do.\n- Read state before replacing, rolling back, or purging. For DNS, PATCH changes the fields you send and PUT replaces the whole record, so read the record first and send its type, name, and content with the change. Prefer a targeted cache purge (files, tags, hosts, or prefixes) over purging everything.\n- Cloudflare reports failures in `errors` with numeric codes and returns `success: false`; read the message instead of retrying the same call.\n- Honor rate-limit waits. Cloudflare documents 1,200 requests per five minutes per user, counted across the dashboard and every token; Connecta's per-runtime window approximates it, and a limited user is blocked for the rest of the window.\n- Treat every create, update, delete, purge, deploy, and upload as a write. For guest calls, classification, and routing, fetch `skills({ name: \"usage\" })`.\n",
-        "key_tail": "- Cloudflare answers a rate limit with HTTP 429; the failure carries `retryAfterMs`. Failed authentication is limited separately (code 10502), so diagnose a credential once with `verify_credential` rather than retrying calls.\n"
-    }
+    "content": "## Accounts, domains and records\n\nResolve account and zone ids before acting. A zone is a domain, found by its name;\nits account id joins it to the account inventory. Cloudflare ids are normally\n32-character hex strings. A default id routes a request; a pin limits its scope.\n\nDNS TTL is in seconds; TTL 1 means automatic. Read the record before changing it.\nPATCH changes supplied fields; PUT replaces the record, so preserve its type,\nname and content. Read state before replacing, rolling back or purging. Prefer\na targeted cache purge by files, tags, hosts or prefixes over purging everything.\n\nHatch data keeps Cloudflare's vendor envelope. For example, select DNS record\nidentities with `fields: [\"result.id\", \"result.name\"]`; a list stays under\n`data.result`. Named account and zone lists keep projected rows with camelCase\naccount and name-server fields.\n\n## Workers, storage and analytics\n\nWorker script source is code; secret binding values are separate and unavailable.\nKV values are application data. Encode a slash inside a KV key or R2 object key\nas `%2F`. R2 requires API-token authentication, rather than a Global API Key.\n\nGraphQL Analytics uses accountTag and zoneTag for account/zone identities.\nFilter every accounts/zones field by equality or an explicit set of those ids.\nA pinned query uses one operation per document and every declared fragment.\nAnalytics Engine SQL is read-only; D1 SQL and Durable Object queries can write.\nAI inference, previews and outbound checks can cost money or activate work.\n\n## Disqualifiers and recovery\n\nCredential minting, rotation, stored secrets, private session captures and signed\nupload or deployment links are unavailable. Use the Cloudflare dashboard for\ncredential administration. A Global API Key cannot change user settings or\nmemberships through this connection.\n\nAfter an authentication failure, use `verify_credential` once to distinguish a\nrejected credential from a permission gap. An operator replaces the credential;\nrepeating the failed request does not add permissions. Cloudflare's global limit\ncounts dashboard traffic and all tokens together, so reduce requests as well as\nhonoring the returned wait.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `cloudflare_api_details`, `cloudflare_api_search`, `list_accounts`, `list_zones`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `cloudflare_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 20, at most 50). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Envelope fields:** hatch data keeps the vendor envelope. Select declared fields with `fields: [\"result.id\", \"result.name\"]`; array traversal also accepts `result[].id`. Named reads keep their projected fields.\n- **Hatch:** `cloudflare_api_search` finds this API's operations and reads no account data, `cloudflare_api_details` shows one operation's contract, and `cloudflare_api_read` calls a reviewed read. `cloudflare_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 70 operations are refused by design; use `cloudflare_api_details` with the method and path to inspect the original operation summary and its separate refusal. Use details for refused methods outside the read/write call schemas; those methods remain unavailable.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "instructionsHeading": "Account instructions"
 };

package/dist/providers/cloudflare/tools.js

@@ -0,0 +1,360 @@
+// Curated, projected tools; the standard hatch covers the pinned REST API.
+import { Effect, Schema } from "effect";
+import { ConnectorCallError } from "../../errors.js";
+import { list, read, write } from "../../http/tools.js";
+import { RequestSecrets } from "../../http/services.js";
+import { checked, schema } from "../_shared/rest/kit.js";
+import { inspectGraphqlQuery } from "./lib/graphql.js";
+import { cloudflareRuntime, cloudflareIndex, SAFETY, WRITE_STEPS, UPLOADS, HEADERS, RawUpload, bytesFromBase64, record, text, invalid, describeErrors, } from "./api.js";
+import { settings } from "./api.js";
+import { cloudflarePage } from "../../http/hatch-paging.js";
+import { isMinChars, isMaxChars } from "../../http/json-schema.js";
+function closed(properties, required = []) {
+    return { type: "object", properties, required, additionalProperties: false };
+}
+export function cloudflareTools({ connection, options, }) {
+    const configured = settings(options), pin = configured.pin, operations = cloudflareIndex;
+    const runtime = cloudflareRuntime(connection, configured);
+    const projectZone = (value) => {
+        const zone = record(value);
+        const account = record(zone["account"]);
+        return {
+            id: zone["id"],
+            name: zone["name"],
+            status: zone["status"] ?? null,
+            paused: zone["paused"] ?? null,
+            type: zone["type"] ?? null,
+            accountId: account["id"] ?? null,
+            accountName: account["name"] ?? null,
+            nameServers: Array.isArray(zone["name_servers"]) ? zone["name_servers"] : [],
+            plan: record(zone["plan"])["name"] ?? null,
+        };
+    };
+    const declarations = [
+        {
+            name: "verify_credential",
+            description: "Verify the configured Cloudflare credential and report its status. Call this first when another call fails with auth_required.",
+            annotations: { readOnlyHint: true },
+            inputSchema: closed({}),
+            outputSchema: {
+                type: "object",
+                properties: {
+                    auth: { type: "string", enum: ["apiToken", "globalApiKey"] },
+                    status: { type: ["string", "null"], description: '"active" for a usable credential.' },
+                    id: { type: ["string", "null"] },
+                    email: { type: ["string", "null"], description: "The Global API Key's user." },
+                    expiresOn: { type: ["string", "null"] },
+                    scope: { type: "string", enum: ["user", "account"], description: "Who owns the token." },
+                    accountId: { type: "string" },
+                },
+                required: ["auth", "status", "scope"],
+            },
+            run: () => runtime.verify(),
+        },
+        {
+            name: "graphql_query",
+            description: "Run a read-only GraphQL Analytics API query (POST /graphql). Mutations and subscriptions are refused before sending; filter by zoneTag or accountTag.",
+            annotations: { readOnlyHint: true },
+            inputSchema: closed({
+                query: { type: "string", minLength: 1, maxLength: 20_000, description: "A GraphQL query document." },
+                variables: { type: "object", description: "Variables the query declares, as JSON." },
+                operationName: {
+                    type: "string",
+                    minLength: 1,
+                    maxLength: 200,
+                    description: "Which query to run when the document has several.",
+                },
+            }, ["query"]),
+            outputSchema: {
+                type: "object",
+                properties: {
+                    data: { description: "The query result." },
+                    errors: { type: "array", description: "GraphQL errors, when Cloudflare returned partial data." },
+                },
+                required: ["data"],
+            },
+            run: (args) => Effect.gen(function* () {
+                const source = String(args["query"]);
+                const variables = record(args["variables"]);
+                const scoped = yield* checked(() => inspectGraphqlQuery(source, variables, {
+                    strict: pin !== undefined,
+                    ...(typeof args["operationName"] === "string" ? { operationName: args["operationName"] } : {}),
+                }));
+                if (pin) {
+                    yield* checked(() => {
+                        if (scoped.openTags.length > 0) {
+                            invalid(`A pinned connector filters GraphQL by zoneTag or accountTag equality or _in, not ${scoped.openTags.join(", ")}.`);
+                        }
+                        if (scoped.unscopedFields.length > 0 || scoped.accountTags.length + scoped.zoneTags.length === 0) {
+                            invalid("A pinned connector's GraphQL queries filter every accounts and zones field by a pinned accountTag or zoneTag.");
+                        }
+                        for (const account of scoped.accountTags)
+                            runtime.assertAccount(account);
+                    });
+                    for (const zone of scoped.zoneTags)
+                        yield* runtime.assertZone(zone);
+                }
+                const graphql = Object.freeze({
+                    method: "POST",
+                    path: "/graphql",
+                    operationId: "graphql",
+                    summary: "GraphQL Analytics API",
+                    tag: "graphql",
+                    server: undefined,
+                    row: -1,
+                });
+                const body = { query: source };
+                if (args["variables"] !== undefined)
+                    body["variables"] = variables;
+                if (typeof args["operationName"] === "string")
+                    body["operationName"] = args["operationName"];
+                const response = yield* runtime.send({
+                    method: "POST",
+                    path: "/graphql",
+                    op: graphql,
+                    params: {},
+                    query: {},
+                    body,
+                });
+                const document = record(response.data);
+                const errors = Array.isArray(document["errors"]) ? document["errors"] : [];
+                if ((document["data"] === undefined || document["data"] === null) && errors.length > 0) {
+                    const redacted = (yield* RequestSecrets).redact(errors);
+                    return yield* checked(() => invalid(`Cloudflare GraphQL rejected the query: ${describeErrors(redacted)}`));
+                }
+                return { data: document["data"] ?? null, ...(errors.length > 0 ? { errors } : {}) };
+            }),
+        },
+        {
+            name: "cloudflare_api_upload",
+            description: "Upload text, base64 bytes, or multipart parts to a reviewed Cloudflare upload operation. Covers Workers scripts, KV values, R2 objects, Pages, Images, Stream, DNS import, and Snippets; never reads local files.",
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            inputSchema: closed({
+                method: { type: "string", enum: ["POST", "PUT", "PATCH"], description: "The operation's HTTP method." },
+                path: {
+                    type: "string",
+                    minLength: 2,
+                    maxLength: 2048,
+                    description: "Concrete path from cloudflare_api_search; encode a / inside an R2 or KV key as %2F.",
+                },
+                query: { type: "object", description: "Query parameters as JSON, named as details lists them." },
+                headers: {
+                    type: "object",
+                    description: "Optional R2 headers.",
+                    properties: Object.fromEntries(Object.entries(HEADERS).map(([name, description]) => [
+                        name,
+                        { type: "string", minLength: 1, maxLength: 40, description },
+                    ])),
+                    additionalProperties: false,
+                },
+                contentType: {
+                    type: "string",
+                    minLength: 1,
+                    maxLength: 200,
+                    description: "Content-Type of a text or base64 body.",
+                },
+                textBody: { type: "string", description: "A UTF-8 body; exclusive with base64Body and parts." },
+                base64Body: { type: "string", description: "Body bytes as base64; exclusive with textBody and parts." },
+                parts: {
+                    type: "array",
+                    maxItems: 100,
+                    description: "multipart/form-data parts; a part with fileName is sent as a file.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string", minLength: 1, maxLength: 200, description: "Form field name, e.g. metadata." },
+                            text: { type: "string", description: "Text value; exclusive with base64." },
+                            base64: { type: "string", description: "Bytes as base64; exclusive with text." },
+                            fileName: {
+                                type: "string",
+                                minLength: 1,
+                                maxLength: 500,
+                                description: "Send as a file with this name.",
+                            },
+                            contentType: { type: "string", minLength: 1, maxLength: 200, description: "The part's Content-Type." },
+                        },
+                        required: ["name"],
+                        additionalProperties: false,
+                    },
+                },
+            }, ["method", "path"]),
+            outputSchema: {
+                type: "object",
+                properties: {
+                    status: { type: "integer", description: "HTTP status." },
+                    data: {
+                        description: "Cloudflare's response envelope after value safety: result, errors, messages, success.",
+                    },
+                },
+                required: ["status", "data"],
+            },
+            run: (args) => Effect.gen(function* () {
+                const preparedUpload = yield* checked(() => {
+                    const method = String(args["method"]);
+                    const prepared = runtime.call(method, String(args["path"]), {
+                        query: record(args["query"]),
+                        ...(Object.keys(record(args["headers"])).length
+                            ? { headers: record(args["headers"]) }
+                            : {}),
+                    });
+                    const refusal = SAFETY.refusal(prepared.method, prepared.op.path) ?? runtime.refuse(prepared);
+                    if (refusal)
+                        invalid(refusal);
+                    if (!UPLOADS.some(([verb, template]) => verb === prepared.op.method && template === prepared.op.path)) {
+                        invalid(`${prepared.op.method} ${prepared.op.path} is not a reviewed upload operation; JSON writes go through cloudflare_api_write.`);
+                    }
+                    const accepted = operations
+                        .contract(prepared.op)
+                        .parameters.filter((parameter) => parameter.in === "query");
+                    for (const name of Object.keys(prepared.query)) {
+                        if (!accepted.some((parameter) => parameter.name === name)) {
+                            invalid(`${prepared.op.path} has no query parameter ${name}; it accepts ${accepted.map((parameter) => parameter.name).join(", ") || "none"}.`);
+                        }
+                    }
+                    const parts = Array.isArray(args["parts"]) ? args["parts"].map(record) : [];
+                    const textBody = typeof args["textBody"] === "string" ? args["textBody"] : undefined;
+                    const base64Body = typeof args["base64Body"] === "string" ? args["base64Body"] : undefined;
+                    if (Number(parts.length > 0) + Number(textBody !== undefined) + Number(base64Body !== undefined) !== 1) {
+                        invalid("cloudflare_api_upload needs exactly one body: textBody, base64Body, or parts.");
+                    }
+                    let upload;
+                    if (parts.length > 0) {
+                        const form = new FormData();
+                        for (const part of parts) {
+                            const name = String(part["name"]);
+                            const value = typeof part["text"] === "string" ? part["text"] : undefined;
+                            const bytes = typeof part["base64"] === "string" ? part["base64"] : undefined;
+                            if (Number(value !== undefined) + Number(bytes !== undefined) !== 1) {
+                                invalid(`Multipart part ${name} needs exactly one of text or base64.`);
+                            }
+                            const fileName = text(part["fileName"]);
+                            const type = text(part["contentType"]);
+                            if (fileName || type || bytes !== undefined) {
+                                const blob = new Blob([value ?? bytesFromBase64(bytes, `part ${name}`)], {
+                                    type: type ?? "application/octet-stream",
+                                });
+                                form.append(name, blob, fileName ?? name);
+                            }
+                            else {
+                                form.append(name, value);
+                            }
+                        }
+                        upload = new RawUpload(form, undefined);
+                    }
+                    else {
+                        upload = new RawUpload(textBody ?? bytesFromBase64(base64Body, "base64Body"), text(args["contentType"]) ??
+                            (textBody !== undefined ? "text/plain; charset=utf-8" : "application/octet-stream"));
+                    }
+                    return { ...prepared, body: upload };
+                });
+                const { status, data } = yield* runtime.sendEnvelope(preparedUpload);
+                return { status, data };
+            }),
+        },
+    ];
+    return [
+        ...["accounts", "zones"].map((noun) => {
+            const zone = noun === "zones";
+            const filters = {
+                name: Schema.optionalKey(Schema.String.check(isMinChars(1), isMaxChars(zone ? 253 : 200)).annotate({
+                    description: zone ? "Exact domain name, e.g. example.com." : "Exact account name.",
+                })),
+                ...(zone
+                    ? {
+                        status: Schema.optionalKey(Schema.Literals(["initializing", "pending", "active", "moved"])),
+                        accountId: Schema.optionalKey(Schema.String.check(isMinChars(1), isMaxChars(64)).annotate({
+                            description: "Only zones in this account.",
+                        })),
+                    }
+                    : {}),
+            };
+            const row = Schema.Struct(zone
+                ? {
+                    id: Schema.optionalKey(Schema.String),
+                    name: Schema.optionalKey(Schema.String),
+                    status: Schema.optionalKey(Schema.NullOr(Schema.String)),
+                    paused: Schema.optionalKey(Schema.NullOr(Schema.Boolean)),
+                    type: Schema.optionalKey(Schema.NullOr(Schema.String)),
+                    accountId: Schema.optionalKey(Schema.NullOr(Schema.String)),
+                    accountName: Schema.optionalKey(Schema.NullOr(Schema.String)),
+                    nameServers: Schema.optionalKey(Schema.Array(Schema.String)),
+                    plan: Schema.optionalKey(Schema.NullOr(Schema.String)),
+                }
+                : {
+                    id: Schema.optionalKey(Schema.String),
+                    name: Schema.optionalKey(Schema.String),
+                    type: Schema.optionalKey(Schema.NullOr(Schema.String)),
+                });
+            const tool = list(connection, {
+                name: `list_${noun}`,
+                description: zone
+                    ? "List Cloudflare zones (domains) by name, status or account; only pinned zones. Resolves domain names to zone/account ids for DNS, cache and analytics."
+                    : "List Cloudflare accounts by name; only pinned accounts. Resolves account ids for zones, Workers, KV and R2.",
+                filters,
+                row,
+                limit: { default: 20, max: 50, description: "Results per page: 5 to 50; default 20." },
+                cursor: "bound",
+                total: true,
+                page: (args, cursor) => Effect.gen(function* () {
+                    if (args.limit < 5)
+                        yield* checked(() => invalid("Cloudflare account and zone lists require limit from 5 to 50."));
+                    const page = cursor === undefined ? 1 : Number(cursor);
+                    if (!Number.isSafeInteger(page) || page < 1)
+                        yield* checked(() => invalid("This cursor contains no valid Cloudflare page."));
+                    const query = { page, per_page: args.limit };
+                    if (args.name !== undefined)
+                        query["name"] = args.name;
+                    if ("status" in args && args.status !== undefined)
+                        query["status"] = args.status;
+                    if ("accountId" in args && args.accountId !== undefined)
+                        query["account.id"] = args.accountId;
+                    const answer = yield* runtime.sendEnvelope(runtime.call("GET", `/${noun}`, { query }));
+                    const body = record(answer.data), info = record(body["result_info"]);
+                    const rows = body["result"];
+                    if (!Array.isArray(rows))
+                        yield* checked(() => {
+                            throw new ConnectorCallError("connector_call_failed", "Cloudflare returned a list without a result array.", { retryable: false });
+                        });
+                    const next = yield* checked(() => cloudflarePage.next(body, { path: `/${noun}`, query, headers: {} }));
+                    const total = pin ? undefined : info["total_count"];
+                    if (total !== undefined && (!Number.isSafeInteger(total) || total < 0))
+                        yield* checked(() => {
+                            throw new ConnectorCallError("connector_call_failed", "Cloudflare returned an invalid exact list total.", { retryable: false });
+                        });
+                    return {
+                        rows: rows.map((item) => zone
+                            ? projectZone(item)
+                            : { id: record(item)["id"], name: record(item)["name"], type: record(item)["type"] ?? null }),
+                        page: {
+                            hasMore: next !== undefined && next !== null,
+                            nextCursor: typeof next === "number" ? String(next) : null,
+                            ...(typeof total === "number" ? { total } : {}),
+                        },
+                    };
+                }),
+            });
+            tool.inputSchema.properties["limit"].minimum = 5;
+            return tool;
+        }),
+        ...declarations.map((declaration) => {
+            const spec = {
+                writeSteps: WRITE_STEPS,
+                name: declaration.name,
+                description: declaration.description,
+                input: Object.keys(declaration.inputSchema.properties ?? {}).length === 0
+                    ? Schema.Struct({})
+                    : schema(declaration.inputSchema),
+                output: schema(declaration.outputSchema),
+                run: (args) => declaration.run(args),
+            };
+            const tool = declaration.annotations.readOnlyHint
+                ? read(connection, {
+                    fields: true,
+                    ...spec,
+                    review: "Credential verification, GraphQL query-only inspection and account/zone lists are read-only; every pin is checked before dispatch.",
+                })
+                : write(connection, { ...spec, destructive: true });
+            return tool;
+        }),
+    ];
+}

package/dist/providers/docs/api.js

@@ -0,0 +1,51 @@
+// Google Docs' vendor on the provider kit (C.7 step 1).
+import { Schema } from "effect";
+import { get, post, vendor } from "../../http/vendor.js";
+import { googleErrors } from "../_shared/google/kit.js";
+import { docsSafety } from "./safety.js";
+import { DOCS_SCOPES } from "./lib/constants.js";
+export const DOCS = {
+    provider: "Google Docs",
+    api: "Google Docs API",
+    scopes: DOCS_SCOPES,
+    // A document is a Drive file: 404 means absent or not shared with this user.
+    notFound: "ambiguous",
+};
+const DocumentId = { documentId: Schema.String };
+export const getDocument = get("getDocument", "/documents/:documentId", {
+    params: DocumentId,
+    query: {
+        includeTabsContent: Schema.optionalKey(Schema.String),
+        suggestionsViewMode: Schema.optionalKey(Schema.String),
+    },
+    success: Schema.Unknown,
+});
+const OPERATIONS = [
+    getDocument,
+    post("createDocument", "/documents", { payload: Schema.Unknown, success: Schema.Unknown }),
+    post("batchUpdate", "/documents/:documentId:batchUpdate", {
+        params: DocumentId,
+        payload: Schema.Unknown,
+        success: Schema.Unknown,
+    }),
+];
+/** The three methods declared by the Docs API v1 Discovery document. */
+export const DocsApi = vendor({ name: "Google Docs", manifestBase: "/v1" }, ...OPERATIONS);
+const standardErrors = googleErrors(DOCS, { standard: true, revisionConflicts: true });
+export const errors = {
+    ...standardErrors,
+    meanings: {
+        ...standardErrors.meanings,
+        conflicts: [
+            ...standardErrors.meanings.conflicts.map((meaning) => meaning.replace(/\.$/, "")),
+            "The document content or revision changed during indexed content paging",
+        ],
+    },
+};
+export const safety = docsSafety(OPERATIONS);
+/** Delegation has no operator credential to test; this probe is never run. */
+export const probe = {
+    operation: getDocument,
+    request: { params: { documentId: "-" } },
+    describe: () => "Google Docs delegation has no credential to test.",
+};

package/dist/providers/docs/index.d.ts

@@ -1,17 +1,6 @@
 import { type GoogleWorkspaceOptions } from "../_shared/google/workspace.js";
+export { DOCS_API_BASE_URL, DOCS_SCOPES } from "./lib/constants.js";
 export type { GoogleServiceAccount, GoogleSubjectContext, GoogleWorkspaceOptions, GoogleWorkspaceSubject, } from "../_shared/google/workspace.js";
-/**
- * The Docs API root. Unlike Gmail there is no per-user path segment: the
- * delegated token's subject decides which documents a request can reach.
- */
-export declare const DOCS_API_BASE_URL = "https://docs.googleapis.com/v1";
-/**
- * Exactly the scope this connection requests, and exactly what the Admin
- * console's domain-wide delegation entry must list for it. `documents` reads
- * and edits Docs the user can reach; it lists nothing and touches no other
- * Drive file type.
- */
-export declare const DOCS_SCOPES: readonly ["https://www.googleapis.com/auth/documents"];
 /** Options for {@link docs}: the shared Workspace delegation options. */
 export type DocsOptions = GoogleWorkspaceOptions;
 /**