@oomol-lab/open-connector 1.6.5 → 1.8.0

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[];

package/src/providers/futunn/actions.js

@@ -0,0 +1,152 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+import { futunnResearchActions } from "./actions.research.js";
+import { futunnTradingActions } from "./actions.trading.js";
+const symbol = s.nonEmptyString("Security code with market prefix, for example US.AAPL or HK.00700.");
+const accountId = s.nonEmptyString("Trading account ID returned by list_accounts, kept as a decimal string.", {
+    pattern: "^[0-9]+$",
+});
+const date = s.string("Date in YYYY-MM-DD format in the market timezone.", { format: "date" });
+const snapshot = s.looseObject("Market snapshot with additional category-specific fields.", {
+    code: symbol,
+    last_price: s.number("Latest traded price."),
+    update_time: s.integer("Quote update timestamp in milliseconds."),
+    volume: s.number("Trading volume in shares or contracts."),
+});
+const bar = s.looseObject("Historical candlestick with additional provider fields.", {
+    time_key: s.integer("Candlestick timestamp in milliseconds."),
+    open: s.number("Opening price."),
+    close: s.number("Closing price."),
+    high: s.number("Highest price."),
+    low: s.number("Lowest price."),
+    volume: s.number("Trading volume before applying volumePrecision."),
+});
+const tradingDay = s.looseObject("Trading day and session details.", {
+    time: date,
+    trade_date_type: s.string("Session type, such as WHOLE or MORNING."),
+    trade_second: s.integer("Total trading seconds in the session."),
+});
+const position = s.looseObject("Position details with additional provider fields.", {
+    code: symbol,
+    stock_name: s.string("Security name."),
+    qty: s.string("Position quantity as a decimal string."),
+    cost_price: s.string("Position cost price as a decimal string."),
+    cost_price_valid: s.boolean("Whether the cost price is valid."),
+    pl_val: s.string("Profit or loss as a decimal string."),
+    pl_val_valid: s.boolean("Whether the profit or loss value is valid."),
+});
+const quoteScope = ["quote:read"];
+const tradeScope = ["trade:read"];
+export const futunnActions = [
+    ...futunnResearchActions,
+    ...futunnTradingActions,
+    defineProviderAction("futunn", {
+        name: "get_market_snapshot",
+        operationType: "read",
+        description: "Get real-time market snapshots and valuation metrics for up to 400 securities.",
+        requiredScopes: quoteScope,
+        inputSchema: s.requiredObject("Securities to query.", {
+            symbols: s.array("Security codes to query.", symbol, { minItems: 1, maxItems: 400 }),
+        }),
+        outputSchema: s.requiredObject("Market snapshot results.", {
+            snapshots: s.array("Market snapshots with prices, volume, valuation and category-specific fields.", snapshot),
+        }),
+    }),
+    defineProviderAction("futunn", {
+        name: "get_history_kline",
+        operationType: "read",
+        description: "Get a page of historical candlesticks, retaining the next-page timestamp and volume precision.",
+        requiredScopes: quoteScope,
+        inputSchema: s.object("Historical candlestick query.", {
+            symbol,
+            start: date,
+            end: s.nonEmptyString("End date in YYYY-MM-DD format, or the previous nextTime converted to a string for pagination."),
+            ktype: s.withEnum(s.integer("Candlestick interval: 1=1min, 2=day, 3=week, 4=month, 5=year, 6=5min, 7=15min, 8=30min, 9=60min. Default 2."), [1, 2, 3, 4, 5, 6, 7, 8, 9]),
+            autype: s.withEnum(s.integer("Price adjustment: 0=none, 1=forward (default), 2=backward."), [0, 1, 2]),
+            num: s.integer("Number of bars requested; default and maximum 370.", {
+                minimum: 1,
+                maximum: 370,
+            }),
+            extendedTime: s.withEnum(s.integer("Extended session: 0=default, 1=US pre/after market, 2=US overnight."), [0, 1, 2]),
+        }, { optional: ["start", "ktype", "autype", "num", "extendedTime"] }),
+        outputSchema: s.requiredObject("Historical candlesticks and pagination metadata.", {
+            bars: s.array("Historical candlesticks in upstream order.", bar),
+            nextTime: s.nullable(s.integer("Next page end timestamp in milliseconds, or null when absent.")),
+            volumePrecision: s.nullable(s.integer("Divide bar volumes by 10 to this power; null when the provider omits precision.")),
+        }),
+    }),
+    defineProviderAction("futunn", {
+        name: "list_trading_days",
+        operationType: "read",
+        description: "List trading days for a market within an inclusive date range.",
+        requiredScopes: quoteScope,
+        inputSchema: s.requiredObject("Market and date range.", {
+            market: s.stringEnum("Market to query.", [
+                "HK",
+                "US",
+                "SH",
+                "SZ",
+                "BJ",
+                "SG",
+                "JP",
+                "KR",
+                "CA",
+                "AU",
+                "JP_FUTURE",
+                "SG_FUTURE",
+            ]),
+            start: date,
+            end: date,
+        }),
+        outputSchema: s.requiredObject("Trading calendar results.", {
+            tradingDays: s.array("Trading dates with session type and trading seconds.", tradingDay),
+        }),
+    }),
+    defineProviderAction("futunn", {
+        name: "list_accounts",
+        operationType: "read",
+        description: "List trading accounts authorized by the connected user.",
+        requiredScopes: tradeScope,
+        inputSchema: s.requiredObject("Authorized account query.", {}),
+        outputSchema: s.requiredObject("Authorized trading accounts.", {
+            accounts: s.array("Authorized accounts; numeric account_id values are returned as lossless decimal strings.", s.looseObject("Authorized account details.", {
+                account_id: s.string("Trading account ID as a lossless decimal string."),
+                security_firm: s.string("Broker identifier."),
+                acc_type: s.string("Account type, such as cash or margin."),
+            })),
+        }),
+    }),
+    defineProviderAction("futunn", {
+        name: "get_account_funds",
+        operationType: "read",
+        description: "Get account assets, cash, buying power and margin balances in the requested currency.",
+        requiredScopes: tradeScope,
+        inputSchema: s.requiredObject("Account funds query.", {
+            accountId,
+            currency: s.nonEmptyString("Display currency, for example USD or HKD; ignored by account types that do not support conversion."),
+        }),
+        outputSchema: s.requiredObject("Account fund balances.", {
+            funds: s.looseObject("Account balances; monetary amounts retain upstream decimal strings.", {
+                total_assets: s.string("Total net assets."),
+                cash: s.string("Cash balance."),
+                power: s.string("Maximum buying power."),
+                currency: s.string("Display currency."),
+            }),
+        }),
+    }),
+    defineProviderAction("futunn", {
+        name: "list_positions",
+        operationType: "read",
+        description: "List account positions, optionally filtered by security code and profit/loss ratio.",
+        requiredScopes: tradeScope,
+        inputSchema: s.object("Account position query.", {
+            accountId,
+            code: symbol,
+            plRatioMin: s.string("Minimum profit/loss percentage as a decimal string, for example 10."),
+            plRatioMax: s.string("Maximum profit/loss percentage as a decimal string, for example 20."),
+        }, { optional: ["code", "plRatioMin", "plRatioMax"] }),
+        outputSchema: s.requiredObject("Account position results.", {
+            positions: s.array("Positions with upstream quantities, prices and profit/loss decimal strings.", position),
+        }),
+    }),
+];

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

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