@oomol-lab/open-connector 1.9.0 → 1.9.2

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

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

package/src/providers/ploid/executors.js

@@ -0,0 +1,119 @@
+import { optionalRecord, optionalString } from "../../core/cast.js";
+import { requiredResponseRecord, runProviderRequest, ProviderRequestError, providerInputError, providerResponseError, defineApiKeyProviderExecutors, defineProviderProxy, } from "../provider-runtime.js";
+import { ploidActions } from "./actions.js";
+import { ploidEndpointByName } from "./actions.js";
+const baseUrl = "https://api.ploid.com";
+async function request(apiKey, name, input, fetcher, parentSignal) {
+    const endpoint = ploidEndpointByName.get(name);
+    let path = endpoint.path;
+    for (const key of endpoint.pathKeys) {
+        const value = String(input[key]);
+        if (value === "." || value === "..")
+            throw providerInputError(`${key} must not be a dot path segment`);
+        path = path.replace(`{${key}}`, encodeURIComponent(value));
+    }
+    const url = new URL(path, baseUrl);
+    for (const key of endpoint.queryKeys) {
+        if (input[key] !== undefined)
+            url.searchParams.set(key, String(input[key]));
+    }
+    if (name === "export_set")
+        url.searchParams.set("format", "json");
+    const body = optionalRecord(input.body);
+    const data = name === "start_dataset" ? { ...body, mode: "async" } : body;
+    const timeoutMs = name === "sync_people_search"
+        ? 150000
+        : name === "create_harness_chat_completion"
+            ? 100000
+            : name === "enrich_person"
+                ? 90000
+                : name === "create_dataset"
+                    ? 70000
+                    : undefined;
+    return runProviderRequest({ label: "Ploid", timeoutMs, signal: parentSignal }, async (signal) => {
+        const headers = new Headers({ authorization: `Bearer ${apiKey}`, accept: "application/json" });
+        if (data !== undefined)
+            headers.set("content-type", "application/json");
+        const idempotencyKey = optionalString(input.idempotencyKey);
+        if (idempotencyKey !== undefined)
+            headers.set("Idempotency-Key", idempotencyKey);
+        const response = await fetcher(url, {
+            method: endpoint.method,
+            headers,
+            body: data === undefined ? undefined : JSON.stringify(data),
+            signal,
+        });
+        const text = await response.text();
+        let payload;
+        if (text.trim()) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch { }
+        }
+        if (!response.ok) {
+            const error = optionalRecord(optionalRecord(payload)?.error);
+            const code = optionalString(error?.code);
+            const message = optionalString(error?.message);
+            const requestId = optionalString(error?.request_id);
+            const detail = [code, message, requestId ? `request_id=${requestId}` : undefined].filter(Boolean).join(": ");
+            throw new ProviderRequestError(response.status, `Ploid request failed (${response.status})${detail ? `: ${detail}` : ""}`, undefined, code && ["invalid_api_key", "expired_api_key", "revoked_api_key"].includes(code)
+                ? "authorization_failed"
+                : code === "insufficient_scope"
+                    ? "authorization_failed"
+                    : "provider_error");
+        }
+        if (name === "enrich_person" &&
+            body?.response_format === "markdown" &&
+            response.headers.get("content-type")?.includes("text/markdown"))
+            return { markdown: text };
+        if (name === "delete_monitor" && !text.trim())
+            return { success: true };
+        if (name === "export_set" && Array.isArray(payload))
+            return { items: payload };
+        const result = requiredResponseRecord(payload, "Ploid response");
+        if (name === "get_person" || name === "get_person_run") {
+            if (!("data" in result))
+                throw providerResponseError("Ploid person response is missing data");
+            const person = optionalRecord(result.data);
+            const runId = optionalString(person?.run_id);
+            const pendingStatus = optionalString(person?.status);
+            if (runId && !pendingStatus)
+                throw providerResponseError("Ploid person run is missing status");
+            return {
+                ...result,
+                status: runId ? pendingStatus : "completed",
+                run_id: runId ?? (name === "get_person_run" ? String(input.id) : undefined),
+            };
+        }
+        return result;
+    });
+}
+async function execute(actionName, values, context) {
+    const { apiKey, fetcher } = context;
+    return request(apiKey, actionName, values, fetcher, context.signal);
+}
+export const credentialValidators = {
+    async apiKey(input, { fetcher, signal }) {
+        const result = await request(input.apiKey, "get_account_profile", {}, fetcher, signal);
+        const profile = requiredResponseRecord(result.data, "Ploid account profile");
+        const name = [optionalString(profile.first_name), optionalString(profile.last_name)]
+            .filter(Boolean)
+            .join(" ")
+            .trim();
+        return {
+            profile: { displayName: name || optionalString(profile.email) || "Ploid API Key" },
+            grantedScopes: [],
+            metadata: { apiBaseUrl: baseUrl },
+        };
+    },
+};
+export const executors = defineApiKeyProviderExecutors("ploid", Object.fromEntries(ploidActions.map((action) => [action.name, (values, context) => execute(action.name, values, context)])));
+export const proxy = defineProviderProxy({
+    service: "ploid",
+    baseUrl: baseUrl,
+    auth: { type: "api_key_authorization", prefix: "Bearer " },
+    customizeRequest({ headers }) {
+        headers.set("accept", "application/json");
+    },
+});

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

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

package/src/providers/porteden/actions.js

@@ -0,0 +1,162 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+const emailId = s.nonEmptyString("Provider-prefixed email ID, such as google:abc123 or m365:xyz789.");
+const bodyType = s.stringEnum("Body content type; defaults to html.", ["html", "text"]);
+const participant = s.object("Email recipient.", {
+    email: s.nonEmptyString("Email address."),
+    name: s.string("Display name."),
+}, { optional: ["name"] });
+const recipients = s.array("Recipient addresses and optional display names.", participant, {
+    minItems: 1,
+});
+const email = s.looseObject("Email with permission-filtered fields and attachment metadata; additional fields are preserved.", {
+    id: s.string("Provider-prefixed email ID."),
+    threadId: s.nullable(s.string("Provider-prefixed thread ID.")),
+    subject: s.nullable(s.string("Email subject.")),
+    from: s.nullable(s.looseObject("Sender details.", {})),
+    to: s.nullable(s.array("Recipients.", s.looseObject("Recipient details.", {}))),
+    body: s.nullable(s.string("Email body when requested and permitted.")),
+    bodyPreview: s.nullable(s.string("Short body preview.")),
+    bodyType: s.nullable(s.string("Body content type.")),
+    receivedAt: s.nullable(s.string("Receipt timestamp in UTC.")),
+    isRead: s.boolean("Whether the email is read."),
+    hasAttachments: s.boolean("Whether attachments exist."),
+    attachments: s.nullable(s.array("Attachment metadata; no file content is downloaded.", s.looseObject("Attachment details.", {}))),
+    labels: s.nullable(s.stringArray("Labels or categories.")),
+    provider: s.string("Source provider, such as GOOGLE or M365."),
+    emailAccountOwner: s.nullable(s.string("Mailbox owner address.")),
+});
+const sent = s.looseObject("Send result; Microsoft 365 can return null message and thread IDs.", {
+    success: s.boolean("Whether the operation succeeded."),
+    emailId: s.nullable(s.string("Provider-prefixed sent email ID, when available.")),
+    threadId: s.nullable(s.string("Provider-prefixed thread ID, when available.")),
+    errorMessage: s.nullable(s.string("Upstream failure details, when available.")),
+});
+const success = s.requiredObject("Successful operation result.", {
+    success: s.boolean("Whether the operation succeeded."),
+});
+export const portedenActions = [
+    defineProviderAction("porteden", {
+        name: "search_emails",
+        operationType: "read",
+        requiredScopes: [],
+        description: "Search emails across connected Gmail and Microsoft 365 accounts. Email access and search_emails permission must be enabled in PortEden; pass nextPageToken as pageToken to continue.",
+        inputSchema: s.object("Email search filters and pagination.", {
+            q: s.string("Free-text search query."),
+            from: s.string("Filter by sender email address."),
+            to: s.string("Filter by recipient email address."),
+            subject: s.string("Partial subject filter."),
+            label: s.string("Label or category filter."),
+            unread: s.boolean("Filter by read status; true selects unread emails."),
+            after: s.string("Emails received after this UTC timestamp.", { format: "date-time" }),
+            before: s.string("Emails received before this UTC timestamp.", { format: "date-time" }),
+            hasAttachment: s.boolean("Filter by attachment presence."),
+            limit: s.integer("Maximum results; defaults to 20, at most 50.", {
+                minimum: 1,
+                maximum: 50,
+            }),
+            includeBody: s.boolean("Include full bodies; defaults to false."),
+            pageToken: s.string("Opaque nextPageToken from the previous result."),
+        }, { required: [] }),
+        outputSchema: s.looseObject("Merged email search results sorted newest first.", {
+            emails: s.array("Matching emails.", email),
+            totalCount: s.integer("Total matching count reported by PortEden."),
+            hasMore: s.boolean("Whether more results are available."),
+            nextPageToken: s.nullable(s.string("Opaque continuation token.")),
+            accessInfo: s.unknown("Active access restrictions, if present."),
+            authWarnings: s.unknown("Upstream account authentication warnings, if present."),
+        }),
+    }),
+    defineProviderAction("porteden", {
+        name: "get_email",
+        operationType: "read",
+        requiredScopes: [],
+        description: "Read a provider-prefixed email, including its body by default, subject to PortEden view_email permissions.",
+        inputSchema: s.object("Email lookup.", { emailId, includeBody: s.boolean("Include full body; defaults to true.") }, { optional: ["includeBody"] }),
+        outputSchema: email,
+    }),
+    defineProviderAction("porteden", {
+        name: "get_thread",
+        operationType: "read",
+        requiredScopes: [],
+        description: "Read a complete email thread in chronological order with body content, subject to PortEden view_thread permissions.",
+        inputSchema: s.requiredObject("Thread lookup.", {
+            threadId: s.nonEmptyString("Provider-prefixed thread ID, such as google:abc123 or m365:xyz789."),
+        }),
+        outputSchema: s.looseObject("Email thread.", {
+            id: s.string("Provider-prefixed thread ID."),
+            subject: s.nullable(s.string("Thread subject.")),
+            messages: s.array("Messages in chronological order.", email),
+            messageCount: s.integer("Message count."),
+            participants: s.array("Thread participants.", s.looseObject("Participant details.", {})),
+            lastMessageAt: s.nullable(s.string("Most recent message timestamp.")),
+            provider: s.string("Source provider."),
+        }),
+    }),
+    defineProviderAction("porteden", {
+        name: "send_email",
+        operationType: "write",
+        requiredScopes: [],
+        description: "Send an email through a connected account with PortEden send_email permission. Choose sendFrom or connectionId when needed; the default account is otherwise used.",
+        inputSchema: s.object("New email.", {
+            to: recipients,
+            cc: s.array("Recipient addresses and optional display names.", participant),
+            bcc: s.array("Recipient addresses and optional display names.", participant),
+            subject: s.string("Email subject."),
+            body: s.string("Email body content."),
+            bodyType,
+            importance: s.stringEnum("Priority; defaults to normal.", ["low", "normal", "high"]),
+            sendFrom: s.nonEmptyString("Connected account email address to send from."),
+            connectionId: s.integer("Provider connection ID to send from."),
+        }, { optional: ["cc", "bcc", "bodyType", "importance", "sendFrom", "connectionId"] }),
+        outputSchema: sent,
+    }),
+    defineProviderAction("porteden", {
+        name: "reply_email",
+        operationType: "write",
+        requiredScopes: [],
+        description: "Reply to an email, preserving its thread, with PortEden reply_to_email permission.",
+        inputSchema: s.object("Email reply.", {
+            emailId,
+            body: s.string("Reply body content."),
+            bodyType,
+            replyAll: s.boolean("Reply to all original recipients except the sending account; defaults to false."),
+        }, { optional: ["bodyType", "replyAll"] }),
+        outputSchema: sent,
+    }),
+    defineProviderAction("porteden", {
+        name: "forward_email",
+        operationType: "write",
+        requiredScopes: [],
+        description: "Forward an email to recipients with PortEden forward_email permission.",
+        inputSchema: s.object("Email forwarding options.", {
+            emailId,
+            to: recipients,
+            cc: s.array("Recipient addresses and optional display names.", participant),
+            body: s.string("Optional message to prepend."),
+            bodyType,
+        }, { optional: ["cc", "body", "bodyType"] }),
+        outputSchema: sent,
+    }),
+    defineProviderAction("porteden", {
+        name: "modify_email",
+        operationType: "write",
+        requiredScopes: [],
+        description: "Change read status or labels/categories. PortEden requires mark_as_read and/or apply_labels permission for the requested changes.",
+        inputSchema: s.requireAnyProperty(s.object("Email property changes.", {
+            emailId,
+            markAsRead: s.boolean("Mark as read (true) or unread (false)."),
+            addLabels: s.stringArray("Labels or categories to add."),
+            removeLabels: s.stringArray("Labels or categories to remove."),
+        }, { optional: ["markAsRead", "addLabels", "removeLabels"] }), ["markAsRead", "addLabels", "removeLabels"]),
+        outputSchema: success,
+    }),
+    defineProviderAction("porteden", {
+        name: "delete_email",
+        operationType: "destructive",
+        requiredScopes: [],
+        description: "Move an email to Trash or Deleted Items with PortEden delete_email permission. This is a recoverable soft delete.",
+        inputSchema: s.requiredObject("Email to move to trash.", { emailId }),
+        outputSchema: success,
+    }),
+];

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

@@ -0,0 +1,140 @@
+import { optionalRecord, optionalRawString } from "../../core/cast.js";
+import { requiredInputString, requiredResponseRecord, ProviderRequestError, runProviderRequest, defineApiKeyProviderExecutors, defineProviderProxy, mapProviderActionHandlers, readProviderProxyErrorMessage, withRetryAfterSeconds, } from "../provider-runtime.js";
+import { portedenActions } from "./actions.js";
+const baseUrl = "https://api.porteden.com";
+const defaultHeaders = { accept: "application/json" };
+async function request({ route, method, data, apiKey, fetcher, parentSignal }) {
+    try {
+        return await runProviderRequest({ signal: parentSignal, label: "PortEden" }, async (signal) => {
+            const url = new URL(`${baseUrl}${route}`);
+            if (method === "GET") {
+                for (const [key, value] of Object.entries(data)) {
+                    if (value != null)
+                        url.searchParams.set(key, String(value));
+                }
+            }
+            const hasBody = method === "POST" || method === "PATCH";
+            const headers = new Headers(defaultHeaders);
+            headers.set("Authorization", `Bearer ${apiKey}`);
+            if (hasBody)
+                headers.set("content-type", "application/json");
+            const response = await fetcher(url.toString(), {
+                method,
+                headers,
+                body: hasBody ? JSON.stringify(data) : undefined,
+                signal,
+            });
+            if (response.status === 204 && (method === "PATCH" || method === "DELETE"))
+                return { success: true };
+            const text = await response.text();
+            let payload;
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                payload = undefined;
+            }
+            const body = optionalRecord(payload);
+            if (!response.ok || body?.success === false) {
+                const detail = [
+                    optionalRawString(body?.code),
+                    optionalRawString(body?.error),
+                    optionalRawString(body?.message),
+                    optionalRawString(body?.errorMessage),
+                ]
+                    .filter(Boolean)
+                    .join(": ") || `HTTP ${response.status}`;
+                throw new ProviderRequestError(response.ok ? 502 : response.status, `PortEden request failed: ${detail}`, undefined, body?.error === "API authentication failed"
+                    ? "authorization_failed"
+                    : response.status === 429
+                        ? "rate_limited"
+                        : "provider_error");
+            }
+            return requiredResponseRecord(payload, "PortEden response");
+        });
+    }
+    catch (error) {
+        if (error instanceof ProviderRequestError)
+            error.message = error.message.split(apiKey).join("[REDACTED]");
+        throw error;
+    }
+}
+const handlers = mapProviderActionHandlers("porteden", portedenActions, (action) => async (dataInput, context) => {
+    const { emailId, threadId, ...data } = dataInput;
+    let route = "/api/access/email/messages";
+    let method = "GET";
+    switch (action.name) {
+        case "get_email":
+            route += `/${encodeURIComponent(String(emailId))}`;
+            break;
+        case "get_thread":
+            route = `/api/access/email/threads/${encodeURIComponent(String(threadId))}`;
+            break;
+        case "send_email":
+            route += "/send";
+            method = "POST";
+            break;
+        case "reply_email":
+            route += `/${encodeURIComponent(String(emailId))}/reply`;
+            method = "POST";
+            break;
+        case "forward_email":
+            route += `/${encodeURIComponent(String(emailId))}/forward`;
+            method = "POST";
+            break;
+        case "modify_email":
+            route += `/${encodeURIComponent(String(emailId))}`;
+            method = "PATCH";
+            break;
+        case "delete_email":
+            route += `/${encodeURIComponent(String(emailId))}`;
+            method = "DELETE";
+            break;
+    }
+    return request({
+        route: route,
+        method: method,
+        data: data,
+        apiKey: context.apiKey,
+        fetcher: context.fetcher,
+        parentSignal: context.signal,
+    });
+});
+export const executors = defineApiKeyProviderExecutors("porteden", handlers, {
+    skipDnsValidation: true,
+});
+export const credentialValidators = {
+    async apiKey(input, { fetcher, signal }) {
+        const body = await request({
+            route: "/api/auth/token/status",
+            method: "GET",
+            data: {},
+            apiKey: requiredInputString(input.apiKey, "API Key"),
+            fetcher: fetcher,
+            parentSignal: signal,
+        });
+        if (body.authenticated !== true)
+            throw new ProviderRequestError(400, "PortEden token is not authenticated", undefined, "invalid_input");
+        return {
+            profile: {
+                displayName: optionalRawString(body.operatorName) || optionalRawString(body.userName) || "PortEden API Key",
+            },
+            grantedScopes: [],
+            metadata: { apiBaseUrl: baseUrl },
+        };
+    },
+};
+export const proxy = defineProviderProxy({
+    service: "porteden",
+    baseUrl,
+    auth: { type: "api_key_authorization", prefix: "Bearer " },
+    skipDnsValidation: true,
+    customizeRequest({ headers }) {
+        for (const [name, value] of Object.entries({ accept: "application/json" }))
+            if (!headers.has(name))
+                headers.set(name, value);
+    },
+    async readError(response) {
+        return new ProviderRequestError(response.status, await readProviderProxyErrorMessage(response, "Provider request failed"), withRetryAfterSeconds(response), response.status === 429 ? "rate_limited" : "provider_error");
+    },
+});

package/src/providers/provider-runtime.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderErrorCode } from "../core/provider-error-codes.ts";
 import type { ProviderDispatchContext, ProviderHttpDispatchOptions } from "../core/provider-http-dispatch.ts";
 import type { ActionExecutor, ExecutionContext, ExecutionResult, ProviderExecutors, ProviderProxyExecutor, ProxyExecutionResult, ProxyResponse, ResolvedCredential, TransitFileWriter } from "../core/types.ts";
 import type { ProviderActionNames } from "./action-contracts.generated.ts";
@@ -149,8 +150,8 @@ export interface ProviderInputFile {
 export declare class ProviderRequestError extends Error {
     readonly status: number;
     readonly details?: unknown;
-    readonly code?: string;
-    constructor(status: number, message: string, details?: unknown, code?: string);
+    readonly code?: ProviderErrorCode;
+    constructor(status: number, message: string, details?: unknown, code?: ProviderErrorCode);
 }
 /** A dispatch denial is retryable and must not be wrapped as a bad provider credential. */
 export declare class ProviderDispatchRequestError extends ProviderRequestError {
@@ -418,6 +419,19 @@ export declare function readProviderJsonBody(response: Response, options: ReadPr
  * Parse an already-read provider response body as JSON.
  */
 export declare function parseProviderJsonBodyText(text: string, options: ReadProviderJsonBodyOptions): unknown;
+interface UploadSourceInput {
+    url: string;
+    fetcher: typeof fetch;
+    fieldName: string;
+    maximumBytes?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** Download an upload source through public-only egress with a bounded body. */
+export declare function downloadUploadSource(input: UploadSourceInput): Promise<{
+    bytes: Uint8Array;
+    contentType?: string;
+}>;
 /**
  * Store a provider-hosted file in the local transit file service when enabled.
  */

package/src/providers/provider-runtime.js

@@ -262,7 +262,7 @@ export async function readProviderProxyResponse(response, options = {}) {
         createError: (message) => new ProviderRequestError(413, message),
     });
     const contentType = response.headers.get("content-type") ?? "";
-    const normalizedContentType = contentType.toLowerCase();
+    const normalizedContentType = contentType.split(";", 1)[0].trim().toLowerCase();
     if (bytes.byteLength === 0) {
         return {
             status: response.status,
@@ -270,7 +270,19 @@ export async function readProviderProxyResponse(response, options = {}) {
             data: null,
         };
     }
-    if (normalizedContentType.includes("json")) {
+    if (!normalizedContentType) {
+        try {
+            return {
+                status: response.status,
+                headers,
+                data: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+            };
+        }
+        catch {
+            // Preserve invalid UTF-8 bytes through the base64 fallback.
+        }
+    }
+    if (normalizedContentType === "application/json" || normalizedContentType.endsWith("+json")) {
         return {
             status: response.status,
             headers,
@@ -303,9 +315,13 @@ export async function readProviderProxyErrorMessage(response, fallbackMessage) {
     return (await readProviderErrorTextBody(response, "proxy error response")) || fallbackMessage;
 }
 function isTextProxyContentType(contentType) {
-    const normalized = contentType.toLowerCase();
+    const normalized = contentType.split(";", 1)[0].trim().toLowerCase();
     return (normalized.startsWith("text/") ||
-        normalized.includes("xml") ||
+        normalized === "application/x-ndjson" ||
+        normalized === "application/xml" ||
+        normalized === "application/xml-external-parsed-entity" ||
+        normalized === "application/xml-dtd" ||
+        normalized.endsWith("+xml") ||
         normalized.includes("javascript") ||
         normalized.includes("x-www-form-urlencoded"));
 }
@@ -814,6 +830,23 @@ export function parseProviderJsonBodyText(text, options) {
         throw new ProviderRequestError(options.invalidJsonStatus ?? 502, options.invalidJsonMessage, error);
     }
 }
+/** Download an upload source through public-only egress with a bounded body. */
+export async function downloadUploadSource(input) {
+    return runProviderRequest({ label: input.fieldName, timeoutMs: input.timeoutMs ?? 15_000, signal: input.signal }, async (signal) => {
+        const response = await createProviderFetch({ fetch: input.fetcher })(input.url, { signal });
+        if (!response.ok) {
+            void response.body?.cancel().catch(() => undefined);
+            throw providerInputError(`${input.fieldName} download failed with HTTP ${response.status}`);
+        }
+        const bytes = await readBoundedResponseBytes(response, {
+            maxBytes: input.maximumBytes ?? 20 * 1024 * 1024,
+            fieldName: input.fieldName,
+            createError: providerInputError,
+            signal,
+        });
+        return { bytes, contentType: response.headers.get("content-type") ?? undefined };
+    });
+}
 /**
  * Store a provider-hosted file in the local transit file service when enabled.
  */