@oomol-lab/open-connector 1.6.4 → 1.7.0

package/src/providers/discordbot/runtime.js

@@ -0,0 +1,124 @@
+import { looseArray, optionalRecord, optionalString, recordOrEmpty } from "../../core/cast.js";
+import { jsonObject } from "../../core/request.js";
+import { providerInputError, ProviderRequestError, requiredInputString } from "../provider-runtime.js";
+// Pin actions to v10. An unversioned route goes to Discord's default version, which is
+// still the deprecated v6: 31-bit numeric permissions, no threads, and a 204 without the
+// member from Modify Guild Member.
+const discordRestBaseUrl = "https://discord.com/api/v10";
+// The proxy stays unversioned so existing proxy paths, including ones that already
+// start with a version such as /v10, keep resolving as before.
+export const discordProxyBaseUrl = "https://discord.com/api";
+/** Send a Discord request and parse the JSON response body. */
+export async function discordbotRequestJson(input) {
+    return readDiscordbotJson(await discordbotRequest(input));
+}
+/**
+ * Send a Discord request whose success may be 200 with a JSON body or 204 with none,
+ * returning null for the 204.
+ */
+export async function discordbotRequestJsonOrNull(input) {
+    const response = await discordbotRequest(input);
+    return response.status === 204 ? null : readDiscordbotJson(response);
+}
+/** Send a Discord request that answers with 204 No Content. */
+export async function discordbotRequestNoContent(input) {
+    await discordbotRequest(input);
+    return { success: true };
+}
+/** Send a Discord request, mapping non-2xx responses to provider errors unless `skipError` is set. */
+export async function discordbotRequest(input) {
+    const url = new URL(`${discordRestBaseUrl}${input.path}`);
+    for (const [key, value] of Object.entries(input.query ?? {})) {
+        if (value !== undefined) {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    const headers = new Headers();
+    if (input.authenticated !== false) {
+        headers.set("authorization", `Bot ${input.context.apiKey}`);
+    }
+    if (input.body !== undefined) {
+        headers.set("content-type", "application/json");
+    }
+    const auditLogReason = optionalString(input.auditLogReason);
+    if (auditLogReason) {
+        // Discord reads the header as URL-encoded UTF-8.
+        headers.set("x-audit-log-reason", encodeURIComponent(auditLogReason));
+    }
+    const response = await input.context.fetcher(url, {
+        method: input.method,
+        headers,
+        body: input.body === undefined ? undefined : JSON.stringify(input.body),
+        signal: input.context.signal,
+    });
+    if (!input.skipError && !response.ok) {
+        throw await toDiscordbotError(response);
+    }
+    return response;
+}
+/**
+ * Read a required snowflake input for use as one URL path segment. Only digits are
+ * accepted, because percent-encoding cannot keep an arbitrary id inside one segment:
+ * URL parsing resolves `.` and `..` as dot segments, and Discord decodes `%2F` into a
+ * path separator before routing. Either would send the request, with the same method
+ * and bot token, to another endpoint: `role_id: ".."` turns a role DELETE into one on
+ * the guild itself, and `user_id: "U/roles/R"` on Add Guild Member grants role R.
+ */
+export function requiredPath(value, field) {
+    const segment = requiredInputString(value, field);
+    if (!/^\d+$/.test(segment)) {
+        throw providerInputError(`${field} must be a numeric Discord snowflake id`);
+    }
+    return segment;
+}
+async function readDiscordbotJson(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        throw new ProviderRequestError(502, "Discord returned invalid JSON");
+    }
+}
+async function toDiscordbotError(response) {
+    const text = await response.text().catch(() => "");
+    let payload;
+    try {
+        payload = optionalRecord(JSON.parse(text));
+    }
+    catch { }
+    const message = optionalString(payload?.message) ??
+        optionalString(payload?.error_description) ??
+        optionalString(payload?.error) ??
+        text;
+    // A form error's message is only "Invalid Form Body"; the failing fields are in `errors`.
+    const formErrors = collectDiscordbotFormErrors(payload?.errors, "");
+    const resolvedMessage = formErrors.length > 0
+        ? `${message}: ${formErrors.join("; ")}`
+        : message || `Discord request failed with ${response.status}`;
+    const details = payload
+        ? jsonObject({ code: payload.code, errors: payload.errors, retry_after: payload.retry_after })
+        : undefined;
+    // Discord answers 403 when the bot lacks a guild or channel permission, such as
+    // "Missing Permissions" or "Missing Access". The token still works, so this must
+    // not read as authorization_failed, which clients treat as "reconnect".
+    if (response.status === 403) {
+        return new ProviderRequestError(403, resolvedMessage, details, "invalid_input");
+    }
+    return new ProviderRequestError(response.status, resolvedMessage, details);
+}
+/**
+ * Flatten Discord's form errors into `path: message` entries. Each failing JSON key,
+ * or array index, nests down to an `_errors` list of `{ code, message }`; an `_errors`
+ * list at the top level describes the request as a whole and has no path.
+ */
+function collectDiscordbotFormErrors(errors, path) {
+    return Object.entries(recordOrEmpty(errors)).flatMap(([key, value]) => {
+        if (key !== "_errors") {
+            return collectDiscordbotFormErrors(value, path ? `${path}.${key}` : key);
+        }
+        return looseArray(value).flatMap((item) => {
+            const message = optionalString(optionalRecord(item)?.message);
+            return message ? [path ? `${path}: ${message}` : message] : [];
+        });
+    });
+}

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

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

package/src/providers/drawio_mcp/executors.js

@@ -0,0 +1,19 @@
+import { isPrivateNetworkAccessAllowed } from "../../core/request.js";
+import { createProviderFetch, defineProviderExecutors, requireCustomCredential } from "../provider-runtime.js";
+import { createDrawioMcpContext, drawioMcpActionHandlers, validateDrawioMcpCredential } from "./runtime.js";
+const service = "drawio_mcp";
+export const executors = defineProviderExecutors({
+    service,
+    handlers: drawioMcpActionHandlers,
+    async createContext(context, fetcher) {
+        const credential = await requireCustomCredential(context, service);
+        return createDrawioMcpContext(credential.values, fetcher, context.signal);
+    },
+    allowPrivateNetwork: isPrivateNetworkAccessAllowed,
+});
+export const credentialValidators = {
+    customCredential(input, { fetcher, signal }) {
+        const guardedFetcher = createProviderFetch({ fetch: fetcher, allowPrivateNetwork: isPrivateNetworkAccessAllowed });
+        return validateDrawioMcpCredential(input.values, guardedFetcher, signal);
+    },
+};

package/src/providers/drawio_mcp/runtime.d.ts

@@ -0,0 +1,8 @@
+import type { CredentialValidationResult } from "../../core/types.ts";
+import type { McpToolOptions } from "../mcp-tools.ts";
+import type { ProviderActionHandlers, ProviderFetch, ProviderRuntimeHandler } from "../provider-runtime.ts";
+export declare const drawioMcpActionHandlers: ProviderActionHandlers<"drawio_mcp", ProviderRuntimeHandler<McpToolOptions>>;
+/** Resolve the MCP server a connection points at; a blank endpoint selects the hosted draw.io server. */
+export declare function createDrawioMcpContext(values: Record<string, string>, fetcher: ProviderFetch, signal?: AbortSignal): McpToolOptions;
+/** Confirm the endpoint serves the draw.io tools and derive a stable identity from the endpoint. */
+export declare function validateDrawioMcpCredential(values: Record<string, string>, fetcher: ProviderFetch, signal?: AbortSignal): Promise<CredentialValidationResult>;

package/src/providers/drawio_mcp/runtime.js

@@ -0,0 +1,175 @@
+import { sha256Hex } from "../../core/aws-sigv4.js";
+import { looseArray, optionalInteger, optionalNumber, optionalRawString, optionalRecord, optionalString, } from "../../core/cast.js";
+import { assertPublicHttpUrl, isPrivateNetworkAccessAllowed } from "../../core/request.js";
+import { callMcpTool, listMcpTools } from "../mcp-tools.js";
+import { parseProviderJsonBodyText, providerInputError, providerResponseError, requiredInputString, } from "../provider-runtime.js";
+const hostedEndpoint = "https://mcp.draw.io/mcp";
+const defaultShapeLimit = 10;
+// The two create_diagram tool errors that judge the submitted source; anything else is a server failure.
+const sourceVerdictPrefixes = ["Could not extract draw.io XML", "Provide exactly one of"];
+const errorsHeading = "ERRORS (will cause rendering issues):\n- ";
+const warningsHeading = "WARNINGS (may cause issues):\n- ";
+export const drawioMcpActionHandlers = {
+    async create_diagram(input, options) {
+        const result = await callMcpTool({
+            ...options,
+            toolName: "create_diagram",
+            arguments: { mermaid: optionalString(input.mermaid), xml: optionalString(input.xml) },
+            transformToolResult: rejectDiagramSource,
+        });
+        const texts = readTextContent(result);
+        const editorUrl = readEditorUrl(texts);
+        if (editorUrl === undefined) {
+            throw providerResponseError("draw.io MCP create_diagram response did not include an editor link; a self-hosted server must be jgraph/drawio-mcp mcp-app-server 1.0.4 or later");
+        }
+        return { editorUrl, ...readFindings(texts) };
+    },
+    async search_shapes(input, options) {
+        const result = await callMcpTool({
+            ...options,
+            toolName: "search_shapes",
+            arguments: {
+                query: requiredInputString(input.query, "query"),
+                limit: optionalInteger(input.limit) ?? defaultShapeLimit,
+            },
+        });
+        return { shapes: readShapes(result) };
+    },
+};
+/** Resolve the MCP server a connection points at; a blank endpoint selects the hosted draw.io server. */
+export function createDrawioMcpContext(values, fetcher, signal) {
+    return {
+        endpoint: normalizeDrawioMcpEndpoint(values.mcpEndpoint),
+        service: "draw.io",
+        fetcher,
+        signal,
+        terminateSession: true,
+        maxResponseBytes: 4 * 1024 * 1024,
+        // tools/list is about 64 KB because create_diagram embeds draw.io's drawing reference in its description.
+        toolListMaxBytes: 1024 * 1024,
+        toolListMaxPages: 5,
+        toolListMaxTools: 100,
+    };
+}
+/** Confirm the endpoint serves the draw.io tools and derive a stable identity from the endpoint. */
+export async function validateDrawioMcpCredential(values, fetcher, signal) {
+    const options = createDrawioMcpContext(values, fetcher, signal);
+    const discovered = new Set((await listMcpTools(options)).map((tool) => tool.name));
+    const missing = Object.keys(drawioMcpActionHandlers).filter((toolName) => !discovered.has(toolName));
+    if (missing.length > 0) {
+        throw providerInputError(`mcpEndpoint does not serve the draw.io MCP tools: missing ${missing.join(", ")}`);
+    }
+    return {
+        profile: {
+            accountId: `drawio_mcp:mcp:${sha256Hex(options.endpoint).slice(0, 16)}`,
+            displayName: `draw.io MCP · ${new URL(options.endpoint).host}`,
+        },
+        grantedScopes: [],
+        metadata: { mcpEndpoint: options.endpoint },
+    };
+}
+function normalizeDrawioMcpEndpoint(value) {
+    const allowPrivateNetwork = isPrivateNetworkAccessAllowed();
+    const url = assertPublicHttpUrl(optionalString(value) ?? hostedEndpoint, {
+        fieldName: "mcpEndpoint",
+        createError: providerInputError,
+        allowPrivateNetwork,
+    });
+    if (url.username || url.password) {
+        throw providerInputError("mcpEndpoint must not include a username or password");
+    }
+    if (url.protocol === "http:" && !allowPrivateNetwork) {
+        throw providerInputError("mcpEndpoint must use https unless private-network access is enabled");
+    }
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+}
+// Also drops structured content: the editor link and findings only ever arrive as text blocks,
+// which the shared result normalizer would otherwise discard in favour of structuredContent.
+function rejectDiagramSource(result) {
+    const message = "content" in result && result.isError ? readTextContent(result).join("\n") : "";
+    if (sourceVerdictPrefixes.some((prefix) => message.startsWith(prefix))) {
+        throw providerInputError(`draw.io rejected the diagram source: ${message.slice(0, 300)}`);
+    }
+    return { ...result, structuredContent: undefined };
+}
+// draw.io puts the editor link on a line of its own after the source echo, which is single-line JSON, and after
+// the XML findings, which quote attribute values from the source verbatim, line breaks included. Skipping the
+// findings and taking the last such line keeps a link written inside the submitted source from being returned instead.
+function readEditorUrl(texts) {
+    return texts
+        .filter((text) => !isFindingsText(text))
+        .flatMap((text) => text.split("\n"))
+        .findLast((line) => line.startsWith("https://") && line.includes("#create="));
+}
+// draw.io reports XML problems in one text block of "ERRORS (...):\n- item" and "WARNINGS (...):\n- item" sections.
+function isFindingsText(text) {
+    return text.startsWith("ERRORS ") || text.startsWith("WARNINGS ");
+}
+function readTextContent(result) {
+    return looseArray(optionalRecord(result)?.content).flatMap((item) => {
+        const content = optionalRecord(item);
+        const text = content?.type === "text" ? optionalRawString(content.text) : undefined;
+        return text === undefined ? [] : [text];
+    });
+}
+// Findings items quote attribute values verbatim, so blank lines and line starts can come from the source. Only
+// draw.io's exact layout splits the block: each heading is followed by the items joined with "\n- ", and a blank
+// line separates the errors section from the warnings section. The layout leaves no way to tell a quoted value from
+// that structure: a value that itself contains "\n- " still reads as two items, and one that contains the whole
+// "\n\nWARNINGS (may cause issues):\n- " separator can move items between errors and warnings. The editor link is
+// unaffected, since readEditorUrl skips the findings block as a whole.
+function readFindings(texts) {
+    const text = texts.find(isFindingsText) ?? "";
+    if (text.startsWith(warningsHeading)) {
+        return { errors: [], warnings: splitFindings(text.slice(warningsHeading.length)) };
+    }
+    if (!text.startsWith(errorsHeading)) {
+        return { errors: [], warnings: [] };
+    }
+    const body = text.slice(errorsHeading.length);
+    const separator = body.lastIndexOf(`\n\n${warningsHeading}`);
+    if (separator < 0) {
+        return { errors: splitFindings(body), warnings: [] };
+    }
+    return {
+        errors: splitFindings(body.slice(0, separator)),
+        warnings: splitFindings(body.slice(separator + 2 + warningsHeading.length)),
+    };
+}
+// draw.io never reports an empty finding, so an empty piece can only come from a quoted value that contains the
+// separator, such as one ending in "\n- ", and is dropped.
+function splitFindings(section) {
+    return section.split("\n- ").filter((item) => item !== "");
+}
+// Newer draw.io servers return structured shapes; the hosted server returns a JSON array as text.
+function readShapes(result) {
+    const structured = optionalRecord(result)?.shapes;
+    const payload = structured === undefined ? parseShapeText(readTextContent(result)[0]) : structured;
+    if (!Array.isArray(payload)) {
+        throw providerResponseError("draw.io MCP search_shapes returned an unexpected payload");
+    }
+    return payload.map(readShape);
+}
+function parseShapeText(text) {
+    if (text === undefined) {
+        throw providerResponseError("draw.io MCP search_shapes response did not include any text");
+    }
+    if (text.startsWith("No shapes found"))
+        return [];
+    return parseProviderJsonBodyText(text, {
+        emptyBody: [],
+        invalidJsonMessage: `draw.io MCP search_shapes returned an unexpected payload: ${text.slice(0, 200)}`,
+    });
+}
+function readShape(value) {
+    const shape = optionalRecord(value);
+    const style = optionalRawString(shape?.style);
+    const width = optionalNumber(shape?.w);
+    const height = optionalNumber(shape?.h);
+    if (!style || width === undefined || height === undefined) {
+        throw providerResponseError("draw.io MCP search_shapes returned a shape without a style or size");
+    }
+    return { title: optionalRawString(shape?.title) ?? "", style, width, height };
+}

package/src/providers/elevenreader/runtime.js

@@ -1,7 +1,7 @@
 import { booleanString, compactObject, optionalBoolean, optionalInteger, optionalRecord, optionalString, requiredString, stringRecord, } from "../../core/cast.js";
 import { readBoundedResponseBytes } from "../../core/request.js";
 import { providerInputError, providerUserAgent, ProviderRequestError } from "../provider-runtime.js";
-const elevenreaderApiBaseUrl = "https://api.elevenlabs.io/v1";
+const elevenreaderApiOrigin = "https://api.elevenlabs.io";
 export const elevenreaderActionHandlers = {
     get_user_info(_input, context) {
         return getElevenreaderUserInfo(context);
@@ -74,7 +74,8 @@ async function getElevenreaderModels(context) {
 }
 async function searchElevenreaderVoices(input, context) {
     const payload = await requestElevenreaderJson({
-        path: "/voices/search",
+        path: "/voices",
+        version: "v2",
         query: compactObject({
             search: optionalString(input.search),
             category: optionalString(input.category),
@@ -163,7 +164,7 @@ async function readElevenreaderText(input, context) {
 }
 async function requestElevenreaderJson(input) {
     const hasBody = input.body !== undefined;
-    const response = await input.fetcher(buildElevenreaderUrl(input.path, input.query), {
+    const response = await input.fetcher(buildElevenreaderUrl(input.path, input.query, input.version), {
         method: hasBody ? "POST" : "GET",
         headers: hasBody ? elevenreaderJsonHeaders(input.apiKey) : elevenreaderHeaders(input.apiKey),
         body: hasBody ? JSON.stringify(input.body) : undefined,
@@ -174,8 +175,8 @@ async function requestElevenreaderJson(input) {
     }
     return readElevenreaderJson(response);
 }
-function buildElevenreaderUrl(path, query) {
-    const url = new URL(`${elevenreaderApiBaseUrl}${path}`);
+function buildElevenreaderUrl(path, query, version = "v1") {
+    const url = new URL(`${elevenreaderApiOrigin}/${version}${path}`);
     for (const [key, value] of Object.entries(query ?? {})) {
         if (value !== undefined) {
             url.searchParams.set(key, value);

package/src/providers/fastmoss_mcp/executors.js

@@ -25,7 +25,7 @@ export const proxy = defineProviderProxy({
     baseUrl: origin,
     auth: { type: "api_key_query", name: "api_key" },
     skipDnsValidation: true,
-    redirect: "error",
+    redirect: "manual",
     allowedEndpoint(value) {
         const url = new URL(value, origin);
         return (url.origin === origin &&
@@ -57,7 +57,7 @@ function connectionInput(key, fetcher, signal) {
         service: "FastMoss",
         fetcher,
         signal,
-        redirect: "error",
+        redirect: "manual",
         terminateSession: true,
         maxResponseBytes: 16 * 1024 * 1024,
     };

package/src/providers/finchina/executors.js

@@ -98,7 +98,7 @@ function mcpInput(apiKey, fetcher, signal) {
         service: "FinChina",
         headers: { "x-api-key": apiKey },
         fetcher,
-        redirect: "error",
+        redirect: "manual",
         terminateSession: true,
     };
 }

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

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

package/src/providers/framejet/executors.js

@@ -0,0 +1,19 @@
+import { defineApiKeyProviderExecutors, defineProviderProxy } from "../provider-runtime.js";
+import { framejetActionHandlers, framejetApiBaseUrl, framejetCaptureTimeoutMs, readFramejetError, validateFramejetApiKey, } from "./runtime.js";
+const service = "framejet";
+export const executors = defineApiKeyProviderExecutors(service, framejetActionHandlers, {
+    skipDnsValidation: true,
+});
+export const proxy = defineProviderProxy({
+    service,
+    baseUrl: framejetApiBaseUrl,
+    auth: { type: "api_key_header", name: "X-Api-Key" },
+    readError: readFramejetError,
+    skipDnsValidation: true,
+    timeoutMs: framejetCaptureTimeoutMs,
+});
+export const credentialValidators = {
+    apiKey(input, { fetcher, signal }) {
+        return validateFramejetApiKey(input.apiKey, fetcher, signal);
+    },
+};

package/src/providers/framejet/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { CredentialValidationResult } from "../../core/types.ts";
+import type { ApiKeyProviderContext, ProviderActionHandlers, ProviderFetch } from "../provider-runtime.ts";
+import { ProviderRequestError } from "../provider-runtime.ts";
+export declare const framejetApiBaseUrl = "https://framejet.dev";
+export declare const framejetCaptureTimeoutMs = 90000;
+type FramejetActionHandler = (input: Record<string, unknown>, context: ApiKeyProviderContext) => Promise<unknown>;
+export declare const framejetActionHandlers: ProviderActionHandlers<"framejet", FramejetActionHandler>;
+/**
+ * Check a key against GET /v1/me, which does not spend a screenshot.
+ */
+export declare function validateFramejetApiKey(apiKey: string, fetcher: ProviderFetch, signal?: AbortSignal): Promise<CredentialValidationResult>;
+/**
+ * Map a failed Framejet response for both actions and the proxy, so a spent quota reads the same on either path.
+ */
+export declare function readFramejetError(response: Response): Promise<ProviderRequestError>;
+export {};

package/src/providers/framejet/runtime.js

@@ -0,0 +1,148 @@
+import { createHmac } from "node:crypto";
+import { optionalIntegerOrNull, optionalRecord, optionalString } from "../../core/cast.js";
+import { readBoundedResponseBytes } from "../../core/request.js";
+import { providerInputError, providerResponseError, providerUserAgent, readProviderErrorTextBody, ProviderRequestError, requiredInputString, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+export const framejetApiBaseUrl = "https://framejet.dev";
+// A capture may wait for slow pages, page steps and goal mode, so it gets more than the default budget.
+// The proxy shares this budget, since GET /v1/take is the capture endpoint on both paths.
+export const framejetCaptureTimeoutMs = 90_000;
+const framejetCaptureParams = ["format", "full_page", "width", "height", "dpr", "clean", "delay", "actions"];
+// Framejet caps each value at 200 characters, which the schema enforces, and the joined list at 1000.
+const framejetMaxValuesLength = 1000;
+export const framejetActionHandlers = {
+    take_screenshot(input, context) {
+        return takeFramejetScreenshot(input, context);
+    },
+    create_signed_url(input, context) {
+        return createFramejetSignedUrl(input, context);
+    },
+};
+/**
+ * Check a key against GET /v1/me, which does not spend a screenshot.
+ */
+export async function validateFramejetApiKey(apiKey, fetcher, signal) {
+    const key = requiredInputString(apiKey, "apiKey");
+    await runProviderRequest({ signal, label: "Framejet" }, async (requestSignal) => {
+        const response = await fetcher(new URL("/v1/me", framejetApiBaseUrl), {
+            headers: framejetHeaders(key),
+            signal: requestSignal,
+        });
+        if (!response.ok) {
+            const error = await readFramejetError(response);
+            // A rejected key is a field error on the connect form, not a reconnect prompt.
+            throw response.status === 401 || response.status === 403 ? providerInputError(error.message) : error;
+        }
+    });
+    return {
+        profile: {
+            accountId: "api_key",
+            displayName: "Framejet API Key",
+        },
+        grantedScopes: [],
+        metadata: {
+            apiBaseUrl: framejetApiBaseUrl,
+            validationEndpoint: "/v1/me",
+        },
+    };
+}
+async function takeFramejetScreenshot(input, context) {
+    const transitFiles = context.transitFiles;
+    if (!transitFiles) {
+        throw new ProviderRequestError(500, "take_screenshot requires transit file storage");
+    }
+    const query = buildFramejetQuery(input, ["goal", "values", "cache"]);
+    if ([...(query.get("values") ?? "")].length > framejetMaxValuesLength) {
+        throw providerInputError(`values must total at most ${framejetMaxValuesLength} characters, including the | separators`);
+    }
+    const url = new URL("/v1/take", framejetApiBaseUrl);
+    url.search = query.toString();
+    return runProviderRequest({ signal: context.signal, label: "Framejet", timeoutMs: framejetCaptureTimeoutMs }, async (signal) => {
+        const response = await context.fetcher(url, { headers: framejetHeaders(context.apiKey), signal });
+        if (!response.ok) {
+            throw await readFramejetError(response);
+        }
+        const bytes = await readBoundedResponseBytes(response, {
+            maxBytes: transitFiles.maxBytes,
+            fieldName: "Framejet screenshot",
+            createError: (message) => new ProviderRequestError(413, message),
+        });
+        const mimeType = response.headers.get("content-type")?.split(";")[0]?.trim() || "image/png";
+        const name = mimeType === "image/jpeg" ? "framejet-screenshot.jpg" : "framejet-screenshot.png";
+        const upload = await transitFiles.create(new File([Uint8Array.from(bytes)], name, { type: mimeType }));
+        return {
+            file: {
+                fileId: upload.fileId,
+                downloadUrl: upload.downloadUrl,
+                sizeBytes: upload.sizeBytes,
+                name: upload.name,
+                mimeType: upload.mimeType,
+            },
+            cache: response.headers.get("x-framejet-cache") === "HIT" ? "HIT" : "MISS",
+            remaining: optionalIntegerOrNull(response.headers.get("x-framejet-remaining")),
+        };
+    });
+}
+async function createFramejetSignedUrl(input, context) {
+    const signingKey = await runProviderRequest({ signal: context.signal, label: "Framejet" }, async (signal) => {
+        const response = await context.fetcher(new URL("/v1/signing-key", framejetApiBaseUrl), {
+            headers: framejetHeaders(context.apiKey),
+            signal,
+        });
+        if (!response.ok) {
+            throw await readFramejetError(response);
+        }
+        return requiredResponseRecord(await response.json(), "Framejet signing key response");
+    });
+    const keyId = optionalString(signingKey.key_id);
+    const secret = optionalString(signingKey.signing_secret);
+    if (!keyId || !secret) {
+        throw providerResponseError("Framejet signing key response is missing key_id or signing_secret");
+    }
+    const query = buildFramejetQuery(input, []);
+    query.set("key_id", keyId);
+    if (typeof input.expires_in === "number") {
+        query.set("expires", String(Math.floor(Date.now() / 1000) + input.expires_in));
+    }
+    // Framejet verifies the exact bytes before "&sig=", so sign the query string exactly as it is sent.
+    const signed = query.toString();
+    const sig = createHmac("sha256", secret).update(signed).digest("hex");
+    return { signed_url: `${framejetApiBaseUrl}/v1/take?${signed}&sig=${sig}` };
+}
+function buildFramejetQuery(input, extraParams) {
+    const query = new URLSearchParams({ url: requiredInputString(input.url, "url") });
+    for (const name of [...framejetCaptureParams, ...extraParams]) {
+        const raw = input[name];
+        const value = Array.isArray(raw) ? raw.join("|") : raw;
+        if (value === undefined || value === null || value === "") {
+            continue;
+        }
+        query.set(name, String(value));
+    }
+    return query;
+}
+function framejetHeaders(apiKey) {
+    return {
+        "user-agent": providerUserAgent,
+        "x-api-key": apiKey,
+    };
+}
+/**
+ * Map a failed Framejet response for both actions and the proxy, so a spent quota reads the same on either path.
+ */
+export async function readFramejetError(response) {
+    const text = (await readProviderErrorTextBody(response, "Framejet error response")).trim();
+    let payload;
+    try {
+        payload = optionalRecord(JSON.parse(text));
+    }
+    catch {
+        payload = undefined;
+    }
+    const message = optionalString(payload?.error) ?? (text || `Framejet request failed with status ${response.status}`);
+    const code = optionalString(payload?.code);
+    const fullMessage = code ? `${message} (${code})` : message;
+    // 402 is Framejet's monthly quota; every other status maps through the shared convention.
+    return response.status === 402
+        ? new ProviderRequestError(402, fullMessage, payload, "insufficient_credit")
+        : new ProviderRequestError(response.status, fullMessage, payload);
+}

package/src/providers/futunn/actions.d.ts

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