@oomol-lab/open-connector 1.8.0 → 1.9.0

package/src/providers/fengshui/executors.js

@@ -0,0 +1,23 @@
+import { requiredInputString, defineApiKeyProviderExecutors, defineProviderProxy } from "../provider-runtime.js";
+import { fengshuiActionHandlers, fengshuiApiBaseUrl, requestFengshuiJson } from "./runtime.js";
+const service = "fengshui";
+export const executors = defineApiKeyProviderExecutors(service, fengshuiActionHandlers);
+export const proxy = defineProviderProxy({
+    service,
+    baseUrl: fengshuiApiBaseUrl,
+    auth: { type: "api_key_header", name: "X-API-Key" },
+    customizeRequest({ headers }) {
+        if (!headers.has("accept"))
+            headers.set("accept", "application/json");
+    },
+});
+export const credentialValidators = {
+    async apiKey(input, { fetcher, signal }) {
+        await requestFengshuiJson("/me", {}, requiredInputString(input.apiKey, "apiKey"), fetcher, signal);
+        return {
+            profile: { displayName: "Feng Shui API Key" },
+            grantedScopes: [],
+            metadata: { apiBaseUrl: fengshuiApiBaseUrl, validationEndpoint: "/me" },
+        };
+    },
+};

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

@@ -0,0 +1,4 @@
+import type { ProviderActionHandlers, ApiKeyProviderContext, ProviderRuntimeHandler } from "../provider-runtime.ts";
+export declare const fengshuiApiBaseUrl = "https://fengshui-api.com/api/v2";
+export declare function requestFengshuiJson(path: string, params: Record<string, unknown>, apiKey: string, fetcher: typeof fetch, callerSignal?: AbortSignal): Promise<Record<string, unknown>>;
+export declare const fengshuiActionHandlers: ProviderActionHandlers<"fengshui", ProviderRuntimeHandler<ApiKeyProviderContext>>;

package/src/providers/fengshui/runtime.js

@@ -0,0 +1,95 @@
+import { looseArray, optionalRecord, optionalRawString } from "../../core/cast.js";
+import { readProviderJsonBody, mapProviderActionSources, providerInputError, ProviderRequestError, providerUserAgent, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+export const fengshuiApiBaseUrl = "https://fengshui-api.com/api/v2";
+export function requestFengshuiJson(path, params, apiKey, fetcher, callerSignal) {
+    return runProviderRequest({ label: "Feng Shui API", signal: callerSignal }, async (signal) => {
+        const url = new URL(`${fengshuiApiBaseUrl}${path}`);
+        for (const [name, value] of Object.entries(params)) {
+            if (value !== undefined && name !== "type") {
+                url.searchParams.set(name, String(value));
+            }
+        }
+        const response = await fetcher(url, {
+            method: "GET",
+            headers: {
+                accept: "application/json",
+                "X-API-Key": apiKey,
+                "user-agent": providerUserAgent,
+            },
+            signal,
+        });
+        let payload;
+        try {
+            payload = await readProviderJsonBody(response, {
+                emptyBody: null,
+                invalidJsonMessage: "Feng Shui API returned invalid JSON",
+            });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            throw new ProviderRequestError(response.ok ? 502 : response.status, response.ok
+                ? "Feng Shui API returned invalid JSON"
+                : `Feng Shui API request failed with status ${response.status}`, undefined, "provider_error");
+        }
+        if (!response.ok) {
+            const problem = optionalRecord(payload);
+            const detail = optionalRawString(problem?.detail) ?? optionalRawString(problem?.title);
+            const errors = looseArray(problem?.errors).flatMap((value) => {
+                const entry = optionalRecord(value);
+                const message = optionalRawString(entry?.message);
+                const parameter = optionalRawString(entry?.parameter);
+                return message ? [parameter ? `${parameter}: ${message}` : message] : [];
+            });
+            const message = [detail, ...errors].filter(Boolean).join("; ") || `Feng Shui API request failed with status ${response.status}`;
+            throw new ProviderRequestError(response.status, message, undefined, response.status === 429 ? "rate_limited" : response.status === 422 ? "invalid_input" : "provider_error");
+        }
+        return requiredResponseRecord(payload, "Feng Shui API response");
+    });
+}
+const actionPaths = {
+    get_zodiac_year: "/zodiac/year",
+    get_zodiac_month: "/zodiac/month",
+    get_zodiac_day: "/zodiac/day",
+    get_zodiac_hour: "/zodiac/hour",
+    get_zodiac_allies: "/zodiac/allies",
+    get_zodiac_enemy: "/zodiac/enemy",
+    get_zodiac_secret_friend: "/zodiac/secret-friend",
+    get_zodiac_peach_blossom: "/zodiac/peach-blossom",
+    get_compatibility: "/compatibility",
+    get_kua: "/feng-shui/kua",
+    get_eight_mansions: "/feng-shui/eight-mansions",
+    get_flying_star: "/feng-shui/flying-star",
+    check_lucky_dimension: "/feng-shui/lucky-dimension",
+    get_key_status: "/me",
+};
+export const fengshuiActionHandlers = mapProviderActionSources("fengshui", actionPaths, (name, path) => (input, context) => {
+    const params = { ...input };
+    if ([
+        "get_zodiac_year",
+        "get_zodiac_month",
+        "get_zodiac_allies",
+        "get_zodiac_enemy",
+        "get_zodiac_secret_friend",
+        "get_zodiac_peach_blossom",
+        "get_compatibility",
+        "get_kua",
+    ].includes(name))
+        params.calendar ??= "lunar";
+    if (name === "check_lucky_dimension")
+        params.unit ??= "mm";
+    for (const field of ["date", "date1", "date2"]) {
+        const date = optionalRawString(params[field]);
+        if (date !== undefined && (date < "1700-01-01" || date > "2300-12-31"))
+            throw providerInputError(`${field} must be between 1700-01-01 and 2300-12-31`);
+    }
+    for (const field of ["animal", "animal1", "animal2"]) {
+        const value = optionalRawString(params[field]);
+        if (value !== undefined)
+            params[field] = value.trim().slice(0, 1).toUpperCase() + value.trim().slice(1).toLowerCase();
+    }
+    const facing = optionalRawString(params.facing);
+    if (facing !== undefined)
+        params.facing = facing.trim();
+    return requestFengshuiJson(name === "get_compatibility" ? `${path}/${params.type}` : path, params, context.apiKey, context.fetcher, context.signal);
+});

package/src/providers/files_com/executors.js

@@ -1,5 +1,5 @@
 import { compactObject, optionalInteger, optionalRawString, optionalRecord, optionalString, requiredString, } from "../../core/cast.js";
-import { assertPublicHttpUrl, readBoundedResponseBytes } from "../../core/request.js";
+import { assertPublicHttpUrl, storeResponseInTransit } from "../../core/request.js";
 import { defineProviderExecutors, defineProviderProxy, providerFetch, providerUserAgent, ProviderRequestError, readProviderErrorTextBody, readProviderTextBody, requireApiKeyCredential, requiredInputString, } from "../provider-runtime.js";
 const service = "files_com";
 const filesComApiHostSuffix = ".files.com";
@@ -140,10 +140,9 @@ async function downloadFilesComFile(input, context) {
     }
     const downloadUrl = readFilesComDownloadUrl(requiredString(payload.download_uri, "download_uri", (message) => new ProviderRequestError(502, message)));
     const downloadSignal = composeFilesComRequestSignal(context.signal);
-    let response;
-    let bytes;
+    const transitName = optionalString(input.fileName) ?? remoteName;
     try {
-        response = await providerFetch(downloadUrl, {
+        const response = await providerFetch(downloadUrl, {
             headers: {
                 accept: "*/*",
                 "user-agent": providerUserAgent,
@@ -154,11 +153,23 @@ async function downloadFilesComFile(input, context) {
             const text = await readProviderErrorTextBody(response, "Files.com download error response");
             throw new ProviderRequestError(response.status >= 500 ? 502 : response.status, text || `files_com download failed with HTTP ${response.status}`);
         }
-        bytes = await readBoundedResponseBytes(response, {
-            maxBytes: context.transitFiles.maxBytes,
+        const mimeType = optionalString(response.headers.get("content-type")) ??
+            optionalString(payload.mime_type) ??
+            "application/octet-stream";
+        const file = await storeResponseInTransit(response, context.transitFiles, {
+            name: transitName,
+            mimeType,
             fieldName: "Files.com download",
             createError: (message) => new ProviderRequestError(413, message),
+            signal: downloadSignal,
         });
+        return {
+            fileId: remotePath,
+            name: remoteName,
+            mimeType,
+            sizeBytes: file.sizeBytes,
+            file,
+        };
     }
     catch (error) {
         if (error instanceof ProviderRequestError) {
@@ -169,18 +180,6 @@ async function downloadFilesComFile(input, context) {
         }
         throw error;
     }
-    const mimeType = optionalString(response.headers.get("content-type")) ??
-        optionalString(payload.mime_type) ??
-        "application/octet-stream";
-    const transitName = optionalString(input.fileName) ?? remoteName;
-    const file = await context.transitFiles.create(new File([Uint8Array.from(bytes)], transitName, { type: mimeType }));
-    return {
-        fileId: remotePath,
-        name: remoteName,
-        mimeType,
-        sizeBytes: file.sizeBytes,
-        file,
-    };
 }
 async function requestAndWrapFilesComJson(input) {
     const payload = await requestFilesComJson({

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

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

package/src/providers/finlight/actions.js

@@ -0,0 +1,130 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+const article = s.object("A financial news article returned by Finlight.", {
+    link: s.string("URL of the original article."),
+    source: s.string("Publisher domain."),
+    title: s.string("Article title."),
+    summary: s.nullable(s.string("Article summary when available.")),
+    publishDate: s.string("Publication date as an ISO date string."),
+    createdAt: s.string("Indexing date, returned when ordering by createdAt."),
+    revisedDate: s.nullable(s.string("Last revision date, returned when ordering by revisedDate.")),
+    language: s.string("Article language as an ISO 639-1 code."),
+    sentiment: s.string("Sentiment: positive, neutral, or negative."),
+    confidence: s.string("Sentiment confidence from 0 to 1 as a stringified number."),
+    content: s.nullable(s.string("Full article content when available under the subscription.")),
+    images: s.stringArray("Article image URLs.", { itemDescription: "An article image URL." }),
+    countries: s.stringArray("Countries related to the article.", {
+        itemDescription: "An ISO 3166-1 alpha-2 country code.",
+    }),
+    categories: s.stringArray("Article categories.", { itemDescription: "An article category." }),
+    companies: s.nullable(s.array("Company entities, subject to subscription access.", s.looseObject("Company identity, confidence, tickers, ISINs, and exchange listings."))),
+}, {
+    required: ["link", "title"],
+    additionalProperties: true,
+});
+export const finlightActions = [
+    defineProviderAction("finlight", {
+        name: "search_articles",
+        description: "Search financial news with sentiment, source, ticker, country, category, date, and pagination filters.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Financial news search options.", {
+            query: s.string("Search query, including Finlight advanced query syntax."),
+            sources: s.stringArray("Restrict sources; use * to include all sources.", {
+                itemDescription: "A source domain or *.",
+            }),
+            optInSources: s.stringArray("Additional sources to include beyond the default set.", {
+                itemDescription: "An additional source domain.",
+            }),
+            excludeSources: s.stringArray("Sources to exclude.", {
+                itemDescription: "A source domain to exclude.",
+            }),
+            tickers: s.stringArray("Stock tickers to match; supports *.", {
+                itemDescription: "A stock ticker or *.",
+            }),
+            countries: s.stringArray("Filter countries the article is about, not publisher or company domicile.", {
+                itemDescription: "An ISO 3166-1 alpha-2 country code.",
+            }),
+            categories: s.array("Filter by article categories.", s.stringEnum("An article category.", [
+                "markets",
+                "economy",
+                "business",
+                "politics",
+                "geopolitics",
+                "regulation",
+                "technology",
+                "energy",
+                "commodities",
+                "crypto",
+                "health",
+                "climate",
+                "security",
+            ])),
+            includeEntities: s.boolean("Include company entities; requires a suitable subscription. Defaults to false."),
+            from: s.nonEmptyString("Start date in YYYY-MM-DD or ISO date format."),
+            to: s.nonEmptyString("End date in YYYY-MM-DD or ISO date format."),
+            language: s.nonEmptyString("ISO 639-1 language filter. Defaults to en, excluding other languages."),
+            orderBy: s.stringEnum("Sort field. Defaults to publishDate.", ["publishDate", "createdAt", "revisedDate"]),
+            order: s.stringEnum("Sort direction. Defaults to DESC.", ["ASC", "DESC"]),
+            pageSize: s.integer("Results per page. Defaults to 20.", { minimum: 1, maximum: 100 }),
+            page: s.integer("Page number, starting at 1. Defaults to 1.", { minimum: 1 }),
+        }, {
+            required: [],
+        }),
+        outputSchema: s.object("Finlight search response with pagination and articles.", {
+            status: s.string("Upstream response status."),
+            page: s.integer("Current page number."),
+            pageSize: s.integer("Requested page size."),
+            articles: s.array("Matching articles on this page.", article),
+        }, {
+            required: ["status", "page", "pageSize", "articles"],
+            additionalProperties: true,
+        }),
+    }),
+    defineProviderAction("finlight", {
+        name: "get_article_by_link",
+        description: "Get a Finlight article by its original URL, optionally including company entities and full content.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Article lookup options.", {
+            link: s.url("Original article URL to look up in Finlight."),
+            includeEntities: s.boolean("Include company entities; requires a suitable subscription. Defaults to false."),
+            includeContent: s.boolean("Deprecated upstream option to include full article content. Defaults to false."),
+        }, {
+            optional: ["includeEntities", "includeContent"],
+        }),
+        outputSchema: s.object("Finlight single article response.", {
+            status: s.string("Upstream response status."),
+            article,
+        }, {
+            required: ["status", "article"],
+            additionalProperties: true,
+        }),
+    }),
+    defineProviderAction("finlight", {
+        name: "list_sources",
+        description: "List Finlight news sources, their languages, countries, and default inclusion status.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Options for listing available news sources.", {}, {
+            optional: [],
+        }),
+        outputSchema: s.object("Available Finlight news sources.", {
+            sources: s.array("Supported sources; availability can change.", s.object("A news source.", {
+                domain: s.string("Publisher domain."),
+                isDefaultSource: s.boolean("Whether the source is included by default."),
+                originCountry: s.string("Publisher country code; may be empty."),
+                languages: s.stringArray("Publisher languages, primary language first.", {
+                    itemDescription: "An ISO 639-1 language code.",
+                }),
+                isCustomSource: s.boolean("Whether this is a custom source enabled for the subscription."),
+                isContentAvailable: s.boolean("Deprecated indication of full content availability on eligible plans."),
+            }, {
+                required: ["domain", "isDefaultSource", "originCountry", "languages"],
+                additionalProperties: true,
+            })),
+        }, {
+            optional: [],
+        }),
+    }),
+];

package/src/providers/finlight/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/finlight/executors.js

@@ -0,0 +1,120 @@
+import { optionalRecord, optionalRawString } from "../../core/cast.js";
+import { readProviderTextBody, defineApiKeyProviderExecutors, defineProviderProxy, mapProviderActionHandlers, ProviderRequestError, providerUserAgent, requiredInputString, requiredResponseRecord, runProviderRequest, isAbortLikeError, } from "../provider-runtime.js";
+import { finlightActions } from "./actions.js";
+const baseUrl = "https://api.finlight.me/v2";
+function requireSources(value) {
+    if (!Array.isArray(value))
+        throw new ProviderRequestError(502, "Finlight returned an invalid sources list", undefined, "provider_error");
+    return value;
+}
+function errorMessage(value) {
+    const message = optionalRawString(value);
+    if (message)
+        return message;
+    if (Array.isArray(value))
+        return value.map(errorMessage).filter(Boolean).join("; ") || undefined;
+    const object = optionalRecord(value);
+    if (!object)
+        return undefined;
+    const constraints = optionalRecord(object.constraints);
+    if (constraints)
+        return errorMessage(Object.values(constraints));
+    return errorMessage(Object.values(object));
+}
+async function request(route, apiKey, fetcher, body, validating = false, parentSignal) {
+    return runProviderRequest({ signal: parentSignal, label: "Finlight" }, async (signal) => {
+        const response = await fetcher(`${baseUrl}${route}`, {
+            method: body === undefined ? "GET" : "POST",
+            headers: {
+                "X-API-KEY": apiKey,
+                accept: "application/json",
+                "content-type": "application/json",
+                "user-agent": providerUserAgent,
+            },
+            body,
+            signal,
+        });
+        let payload;
+        try {
+            payload = await JSON.parse(await readProviderTextBody(response, "finlight response", undefined, signal));
+        }
+        catch (error) {
+            if (error instanceof ProviderRequestError || isAbortLikeError(error))
+                throw error;
+            if (response.ok)
+                throw new ProviderRequestError(502, "Finlight returned invalid JSON", undefined, "provider_error");
+        }
+        if (!response.ok) {
+            const result = optionalRecord(payload);
+            const message = (errorMessage(result?.message) ||
+                errorMessage(result?.errors) ||
+                optionalRawString(result?.error) ||
+                `Finlight request failed with HTTP ${response.status}`).replaceAll(apiKey, "[REDACTED]");
+            const invalidKey = response.status === 401 && result?.statusCode === 401 && result.message === "Unauthorized";
+            throw new ProviderRequestError(invalidKey && validating ? 400 : response.status, message, undefined, invalidKey
+                ? validating
+                    ? "invalid_input"
+                    : "authorization_failed"
+                : response.status === 429
+                    ? "rate_limited"
+                    : "provider_error");
+        }
+        return payload;
+    });
+}
+export const executors = defineApiKeyProviderExecutors("finlight", mapProviderActionHandlers("finlight", finlightActions, (action) => async (input, context) => {
+    const apiKey = context.apiKey;
+    const fetcher = context.fetcher;
+    if (action.name === "list_sources") {
+        return {
+            sources: requireSources(await request("/sources", apiKey, fetcher, undefined, undefined, context.signal)),
+        };
+    }
+    let result;
+    if (action.name === "search_articles") {
+        result = await request("/articles", apiKey, fetcher, JSON.stringify(input), undefined, context.signal);
+    }
+    else {
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(input)) {
+            if (value !== undefined)
+                query.set(key, String(value));
+        }
+        result = await request(`/articles/by-link?${query}`, apiKey, fetcher, undefined, undefined, context.signal);
+    }
+    const envelope = requiredResponseRecord(result, "Finlight response");
+    if (action.name === "search_articles") {
+        if (!Array.isArray(envelope.articles))
+            throw new ProviderRequestError(502, "Finlight response is missing articles", undefined, "provider_error");
+    }
+    else {
+        requiredResponseRecord(envelope.article, "Finlight article");
+    }
+    return envelope;
+}), { skipDnsValidation: true });
+export const credentialValidators = {
+    async apiKey(input, { fetcher }) {
+        const result = await request("/sources", requiredInputString(input.apiKey, "API Key"), fetcher, undefined, true);
+        requireSources(result);
+        return {
+            profile: { displayName: "Finlight API Key" },
+            grantedScopes: [],
+            metadata: { validationEndpoint: "/v2/sources" },
+        };
+    },
+};
+export const proxy = defineProviderProxy({
+    service: "finlight",
+    baseUrl,
+    auth: { type: "api_key_header", name: "X-API-KEY" },
+    skipDnsValidation: true,
+    customizeRequest({ headers }) {
+        for (const [key, value] of Object.entries({
+            accept: "application/json",
+            "content-type": "application/json",
+            "user-agent": providerUserAgent,
+        }))
+            if (!headers.has(key))
+                headers.set(key, value);
+    },
+});

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

@@ -1,7 +1,11 @@
 import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
 import type { ProviderActionHandlers } from "../provider-runtime.ts";
-import type { ApiKeyProviderContext } from "../provider-runtime.ts";
-type FirecrawlActionContext = ApiKeyProviderContext;
+interface FirecrawlActionContext {
+    apiKey: string;
+    apiBaseUrl: string;
+    fetcher: typeof fetch;
+    signal?: AbortSignal;
+}
 type FirecrawlActionHandler = (input: Record<string, unknown>, context: FirecrawlActionContext) => Promise<unknown>;
 export declare const firecrawlActionHandlers: ProviderActionHandlers<"firecrawl", FirecrawlActionHandler>;
 export declare const executors: ProviderExecutors;

package/src/providers/firecrawl/executors.js

@@ -1,7 +1,8 @@
 import { compactObject, optionalNumber, optionalRecord, optionalString, pickOptionalBoolean } from "../../core/cast.js";
-import { defineApiKeyProviderExecutors, defineProviderProxy, providerUserAgent, ProviderRequestError, } from "../provider-runtime.js";
+import { assertPublicHttpUrl, isPrivateNetworkAccessAllowed } from "../../core/request.js";
+import { createProviderFetch, defineProviderExecutors, defineProviderProxy, providerInputError, providerUserAgent, ProviderRequestError, requireApiKeyCredential, } from "../provider-runtime.js";
 const service = "firecrawl";
-const firecrawlApiBaseUrl = "https://api.firecrawl.dev";
+const defaultFirecrawlApiBaseUrl = "https://api.firecrawl.dev";
 const firecrawlScrapeOptionAliasKeys = [
     "scrapeOptions_actions",
     "scrapeOptions_formats",
@@ -56,18 +57,39 @@ export const firecrawlActionHandlers = {
     token_usage_get: firecrawlGetAction(() => "/v2/team/token-usage"),
     token_usage_get_historical: firecrawlGetAction(() => "/v2/team/token-usage/historical", buildHistoricalUsageQuery),
 };
-export const executors = defineApiKeyProviderExecutors(service, firecrawlActionHandlers);
+export const executors = defineProviderExecutors({
+    service,
+    handlers: firecrawlActionHandlers,
+    async createContext(context, fetcher) {
+        const credential = await requireApiKeyCredential(context, service);
+        return {
+            apiKey: credential.apiKey,
+            apiBaseUrl: normalizeFirecrawlApiBaseUrl(credential.values.baseUrl),
+            fetcher,
+            signal: context.signal,
+        };
+    },
+    allowPrivateNetwork: isPrivateNetworkAccessAllowed,
+});
 export const proxy = defineProviderProxy({
     service,
-    baseUrl: firecrawlApiBaseUrl,
+    baseUrl: async (context) => {
+        const credential = await requireApiKeyCredential(context, service);
+        return normalizeFirecrawlApiBaseUrl(credential.values.baseUrl);
+    },
     auth: { type: "api_key_authorization", prefix: "Bearer " },
-    skipDnsValidation: true,
+    allowPrivateNetwork: isPrivateNetworkAccessAllowed,
 });
 export const credentialValidators = {
     async apiKey(input, { fetcher, signal }) {
+        const apiBaseUrl = normalizeFirecrawlApiBaseUrl(input.values.baseUrl);
         const payload = optionalRecord(await firecrawlRequest({
             apiKey: input.apiKey,
-            fetcher,
+            apiBaseUrl,
+            // Re-guard the shared validator fetcher with the private-network
+            // opt-in so a self-hosted instance on a private network validates
+            // when the deployment allows it.
+            fetcher: createProviderFetch({ fetch: fetcher, allowPrivateNetwork: isPrivateNetworkAccessAllowed }),
             signal,
             path: "/v2/team/credit-usage",
             phase: "validate",
@@ -79,7 +101,7 @@ export const credentialValidators = {
             },
             grantedScopes: [],
             metadata: compactObject({
-                apiBaseUrl: firecrawlApiBaseUrl,
+                apiBaseUrl,
                 validationEndpoint: "/v2/team/credit-usage",
                 teamCreditUsage: optionalRecord(payload?.data),
                 success: typeof payload?.success === "boolean" ? payload.success : undefined,
@@ -90,6 +112,7 @@ export const credentialValidators = {
 function firecrawlPostAction(path, buildBody) {
     return (input, context) => firecrawlRequest({
         apiKey: context.apiKey,
+        apiBaseUrl: context.apiBaseUrl,
         fetcher: context.fetcher,
         signal: context.signal,
         method: "POST",
@@ -101,6 +124,7 @@ function firecrawlPostAction(path, buildBody) {
 function firecrawlGetAction(buildPath, buildQuery) {
     return (input, context) => firecrawlRequest({
         apiKey: context.apiKey,
+        apiBaseUrl: context.apiBaseUrl,
         fetcher: context.fetcher,
         signal: context.signal,
         path: buildPath(input),
@@ -111,6 +135,7 @@ function firecrawlGetAction(buildPath, buildQuery) {
 function firecrawlDeleteAction(buildPath) {
     return (input, context) => firecrawlRequest({
         apiKey: context.apiKey,
+        apiBaseUrl: context.apiBaseUrl,
         fetcher: context.fetcher,
         signal: context.signal,
         method: "DELETE",
@@ -166,8 +191,34 @@ function buildScrapeOptionsFromInput(input) {
     });
     return Object.keys(flattened).length > 0 ? flattened : undefined;
 }
+/**
+ * Resolves the Firecrawl API base URL for a connection. Empty input targets
+ * the Firecrawl cloud API; otherwise the self-hosted instance URL is
+ * validated, embedded credentials are rejected, and query, hash, and trailing
+ * slashes are removed while any reverse-proxy path prefix is kept.
+ * Private/overlay targets are only accepted when the deployment opts in
+ * through `OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK`.
+ */
+function normalizeFirecrawlApiBaseUrl(value) {
+    const instanceUrl = optionalString(value);
+    if (!instanceUrl) {
+        return defaultFirecrawlApiBaseUrl;
+    }
+    const url = assertPublicHttpUrl(instanceUrl, {
+        fieldName: "baseUrl",
+        createError: providerInputError,
+        allowPrivateNetwork: isPrivateNetworkAccessAllowed(),
+    });
+    if (url.username || url.password) {
+        throw providerInputError("baseUrl must not include credentials");
+    }
+    url.hash = "";
+    url.search = "";
+    url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString().replace(/\/$/u, "");
+}
 async function firecrawlRequest(input) {
-    const url = new URL(input.path, firecrawlApiBaseUrl);
+    const url = new URL(`${input.apiBaseUrl}${input.path}`);
     for (const [key, value] of Object.entries(input.query ?? {})) {
         if (value == null) {
             continue;
@@ -229,7 +280,7 @@ function createFirecrawlError(status, payload, phase) {
         return new ProviderRequestError(status, message, payload);
     }
     if (status === 401 || status === 403) {
-        return new ProviderRequestError(phase === "validate" ? 400 : 401, message, payload);
+        return new ProviderRequestError(phase === "validate" ? 400 : status, message, payload, phase === "validate" ? "invalid_input" : "provider_error");
     }
     if (status === 429) {
         return new ProviderRequestError(429, message, payload);

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

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