@oomol-lab/open-connector 1.7.0 → 1.8.0

package/src/providers/zendesk/trigger-on-event.js

@@ -0,0 +1,188 @@
+import { IntegrationConnectionError, PermanentIntegrationError, TransientIntegrationError, } from "../../triggers/common/integration.js";
+import { bytes, verifyBase64Hmac } from "../../triggers/signature.js";
+import { snapshot, endpoint } from "./trigger-on-event.definition.js";
+const signatureToleranceMs = 5 * 60 * 1_000;
+export const zendeskEvent = {
+    initialState: { checkpoint: null, subscription: {} },
+    snapshot,
+    async receive(context) {
+        const signingSecret = subscriptionSecret(context.state);
+        const timestamp = context.header("x-zendesk-webhook-signature-timestamp");
+        const signedAt = timestamp == null ? Number.NaN : Date.parse(timestamp);
+        if (signingSecret == null ||
+            timestamp == null ||
+            !Number.isFinite(signedAt) ||
+            Math.abs(context.now.getTime() - signedAt) > signatureToleranceMs ||
+            !(await verifyBase64Hmac(signingSecret, [bytes(timestamp), context.rawBody], context.header("x-zendesk-webhook-signature")))) {
+            return { body: "", contentType: "text/plain", outcome: "respond", status: 404 };
+        }
+        if (context.payload == null || typeof context.payload != "object" || Array.isArray(context.payload)) {
+            return { outcome: "ignored", reason: "Zendesk event body is missing." };
+        }
+        const payload = context.payload;
+        const event = payload.type;
+        if (typeof event != "string" || event.length == 0)
+            return { outcome: "ignored", reason: "Zendesk event type is missing." };
+        if (!context.config.events.includes(event))
+            return { outcome: "ignored", reason: "Zendesk event is not subscribed." };
+        const deliveryId = typeof payload.id == "string" ? payload.id : "";
+        const subject = payload.subject;
+        return {
+            dedupeKey: deliveryId.length == 0 ? undefined : deliveryId,
+            outcome: "event",
+            outputs: {
+                body: payload,
+                deliveryId,
+                event,
+                ...(typeof subject == "string" ? { subject } : {}),
+            },
+        };
+    },
+    async reconcile(context) {
+        const state = requireState(context.state);
+        const listed = await findByEndpoint(context);
+        const known = subscriptionId(state);
+        if (!context.active) {
+            for (const webhookId of known == null ? listed : [...new Set([known, ...listed])])
+                await remove(context, webhookId);
+            await state.saveSubscription({}, later(context.now));
+            return { outcome: "ready" };
+        }
+        let webhookId = known ?? listed[0];
+        if (webhookId == null) {
+            const created = await request(context, "webhook create", {
+                body: desired(context),
+                endpoint,
+                method: "POST",
+            });
+            success(created, "webhook create");
+            webhookId = readId(record(created.data)?.webhook);
+        }
+        else {
+            const aligned = await request(context, "webhook update", {
+                body: desired(context),
+                endpoint: `${endpoint}/${webhookId}`,
+                method: "PUT",
+            });
+            if (aligned.status == 404) {
+                await state.saveSubscription({}, context.now);
+                return { outcome: "pending" };
+            }
+            success(aligned, "webhook update");
+        }
+        await state.saveSubscription({ ...state.subscription, webhookId }, context.now);
+        for (const duplicate of listed.filter((value) => value != webhookId))
+            await remove(context, duplicate);
+        await state.saveSubscription({ signingSecret: await readSigningSecret(context, webhookId), webhookId }, later(context.now));
+        return { outcome: "ready" };
+    },
+};
+function desired(context) {
+    return {
+        webhook: {
+            description: "Managed by Open Flow. Do not edit.",
+            endpoint: context.endpointUrl,
+            http_method: "POST",
+            name: name(context.endpointUrl),
+            request_format: "json",
+            status: "active",
+            subscriptions: [...new Set(context.config.events)],
+        },
+    };
+}
+async function findByEndpoint(context) {
+    const matches = [];
+    let after;
+    for (let page = 0; page < 10; page += 1) {
+        const result = await request(context, "webhook list", {
+            endpoint,
+            method: "GET",
+            query: {
+                "filter[name_contains]": name(context.endpointUrl),
+                "page[size]": "100",
+                ...(after == null ? {} : { "page[after]": after }),
+            },
+        });
+        success(result, "webhook list");
+        const listing = record(result.data);
+        const webhooks = Array.isArray(listing?.webhooks) ? listing.webhooks : [];
+        for (const item of webhooks) {
+            const value = record(item);
+            if (value?.endpoint === context.endpointUrl && typeof value.id == "string")
+                matches.push(value.id);
+        }
+        const meta = record(listing?.meta);
+        if (meta?.has_more !== true || typeof meta.after_cursor != "string")
+            return matches;
+        after = meta.after_cursor;
+    }
+    return matches;
+}
+async function remove(context, webhookId) {
+    const result = await request(context, "webhook delete", {
+        endpoint: `${endpoint}/${webhookId}`,
+        method: "DELETE",
+    });
+    if (result.status != 404)
+        success(result, "webhook delete");
+}
+async function request(context, operation, value) {
+    try {
+        return await context.connector.execute(value, context.signal);
+    }
+    catch (cause) {
+        if (cause instanceof IntegrationConnectionError)
+            throw cause;
+        throw new TransientIntegrationError(`Zendesk ${operation} request failed.`, { cause });
+    }
+}
+function success(result, operation) {
+    if (result.status >= 200 && result.status < 300)
+        return;
+    if (result.status == 401 || result.status == 403)
+        throw new IntegrationConnectionError(`Zendesk ${operation} rejected the Connection.`);
+    if ([400, 404, 422].includes(result.status))
+        throw new PermanentIntegrationError(`Zendesk ${operation} rejected the subscription.`);
+    throw new TransientIntegrationError(`Zendesk ${operation} failed with status ${result.status}.`);
+}
+function name(url) {
+    return `open-flow-${url.slice(url.lastIndexOf("/") + 1)}`;
+}
+function readId(value) {
+    const webhookId = record(value)?.id;
+    if (typeof webhookId != "string")
+        throw new TransientIntegrationError("Zendesk webhook response is missing its ID.");
+    return webhookId;
+}
+function requireState(value) {
+    if (value == null)
+        throw new PermanentIntegrationError("Zendesk Integration state is missing.");
+    return value;
+}
+function subscriptionId(state) {
+    const value = state.subscription.webhookId;
+    return typeof value == "string" && value.length > 0 ? value : null;
+}
+function subscriptionSecret(state) {
+    const value = state?.subscription.signingSecret;
+    return typeof value == "string" && value.length > 0 ? value : null;
+}
+async function readSigningSecret(context, webhookId) {
+    const result = await request(context, "webhook signing secret", {
+        endpoint: `${endpoint}/${webhookId}/signing_secret`,
+        method: "GET",
+    });
+    success(result, "webhook signing secret");
+    const secret = record(record(result.data)?.signing_secret)?.secret;
+    if (typeof secret != "string" || secret.length == 0)
+        throw new TransientIntegrationError("Zendesk webhook signing secret response is invalid.");
+    return secret;
+}
+function later(now) {
+    return new Date(now.getTime() + 30 * 24 * 60 * 60 * 1_000);
+}
+function record(value) {
+    return value != null && typeof value == "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/src/saas/saas-cleanup-service.d.ts

@@ -0,0 +1,26 @@
+import type { RuntimeLogger } from "../core/types.ts";
+import type { ConnectionRequestStore } from "../server/storage/connection-request-store.ts";
+import type { SaasProjectStore } from "../server/storage/saas-project-store.ts";
+import { SaasClient } from "./saas-client.ts";
+export interface SaasCleanupServiceOptions {
+    store: SaasProjectStore;
+    requests: ConnectionRequestStore;
+    client?: SaasClient;
+    logger?: RuntimeLogger;
+}
+/** Resumable deletion of ordinary SaaS accounts; never creates or reconnects an account. */
+export declare class SaasCleanupService {
+    private readonly options;
+    private readonly client;
+    private readonly shutdown;
+    private pending?;
+    private timer?;
+    private started;
+    constructor(options: SaasCleanupServiceOptions);
+    run(): Promise<void>;
+    /** Node owns this timer; Workers invoke run from their scheduled entry point instead. */
+    start(): void;
+    close(): Promise<void>;
+    private runBatch;
+    private nextAttempt;
+}

package/src/saas/saas-cleanup-service.js

@@ -0,0 +1,124 @@
+import { SaasClient, SaasError } from "./saas-client.js";
+/** Resumable deletion of ordinary SaaS accounts; never creates or reconnects an account. */
+export class SaasCleanupService {
+    options;
+    client;
+    shutdown = new AbortController();
+    pending;
+    timer;
+    started = false;
+    constructor(options) {
+        this.options = options;
+        this.client = options.client ?? new SaasClient();
+    }
+    run() {
+        if (this.shutdown.signal.aborted)
+            return Promise.resolve();
+        this.pending ??= this.runBatch()
+            .catch(() => {
+            this.options.logger?.warn({ errorCode: "saas_cleanup_failed" }, "SaaS cleanup batch failed; pending work is retained");
+        })
+            .finally(() => {
+            this.pending = undefined;
+        });
+        return this.pending;
+    }
+    /** Node owns this timer; Workers invoke run from their scheduled entry point instead. */
+    start() {
+        if (this.started || this.shutdown.signal.aborted)
+            return;
+        this.started = true;
+        const tick = () => {
+            void this.run().finally(() => {
+                if (this.shutdown.signal.aborted)
+                    return;
+                this.timer = setTimeout(tick, 60_000);
+                this.timer.unref?.();
+            });
+        };
+        tick();
+    }
+    async close() {
+        this.shutdown.abort();
+        clearTimeout(this.timer);
+        await this.pending;
+    }
+    async runBatch() {
+        await this.options.requests.expireSaas();
+        const deadline = Date.now() + 50_000;
+        for (let count = 0; count < 10 && Date.now() < deadline && !this.shutdown.signal.aborted; count++) {
+            const project = await this.options.store.getProject();
+            if (!project)
+                return;
+            const task = await this.options.store.claimCleanup(Date.now());
+            if (!task)
+                return;
+            const signal = AbortSignal.any([
+                this.shutdown.signal,
+                AbortSignal.timeout(Math.max(1, Math.min(30_000, deadline - Date.now()))),
+            ]);
+            try {
+                if (project.id !== task.managedProjectId)
+                    throw new SaasError("oauth_source_mismatch", "Cleanup project identity does not match.", 409);
+                let accountId = task.connectedAccountId;
+                if (!accountId) {
+                    if (!task.remoteRequestId) {
+                        await this.options.store.retryCleanup(task, Date.now(), "oauth_source_result_unknown", true);
+                        continue;
+                    }
+                    const result = await this.client.getRequest(project, task.remoteRequestId, signal);
+                    if (result.providerConfigId !== task.providerConfigId ||
+                        result.externalUserId !== task.externalUserId ||
+                        result.service !== task.service ||
+                        result.alias !== `connect-${task.id.slice("request:".length)}`)
+                        throw new SaasError("oauth_source_mismatch", "Cleanup request identity does not match.", 409);
+                    if (result.status === "initiated") {
+                        const expired = Date.now() >= Date.parse(task.requestExpiresAt ?? result.expiresAt) + 86_400_000;
+                        await this.options.store.retryCleanup(task, Date.now() + 60_000, expired ? "oauth_source_result_unknown" : "authorization_pending", expired);
+                        continue;
+                    }
+                    if (result.status !== "connected") {
+                        await this.options.store.finishCleanup(task);
+                        continue;
+                    }
+                    accountId = result.connectedAccountId;
+                    if (!(await this.options.store.saveCleanupAccount(task, accountId)))
+                        continue;
+                    task.connectedAccountId = accountId;
+                }
+                signal.throwIfAborted();
+                await this.client.deleteAccount(project, {
+                    providerConfigId: task.providerConfigId,
+                    externalUserId: task.externalUserId,
+                    connectedAccountId: accountId,
+                }, signal);
+                await this.options.store.finishCleanup(task);
+            }
+            catch (error) {
+                const code = error instanceof SaasError ? error.code : "saas_cleanup_failed";
+                if (code === "oauth_source_unauthorized")
+                    await this.options.store.pauseCleanup(task, project.apiKey);
+                const manual = code === "oauth_source_mismatch" ||
+                    code === "oauth_source_protocol_error" ||
+                    (code === "oauth_source_not_found" && !task.connectedAccountId);
+                await this.options.store.retryCleanup(task, this.nextAttempt(task, error), code === "oauth_source_not_found" && !task.connectedAccountId ? "oauth_source_result_unknown" : code, manual);
+                if (!this.shutdown.signal.aborted)
+                    this.options.logger?.warn({ taskId: task.id, errorCode: code, manual }, code === "oauth_source_unauthorized"
+                        ? "SaaS cleanup paused; update the project key to resume"
+                        : "SaaS cleanup deferred");
+                if (code === "oauth_source_unauthorized" || this.shutdown.signal.aborted)
+                    return;
+            }
+        }
+    }
+    nextAttempt(task, error) {
+        let delay = Math.min(300_000, 60_000 * 2 ** Math.min(task.attempts, 3));
+        if (error instanceof SaasError && error.retryAfter) {
+            const seconds = Number(error.retryAfter);
+            const until = Number.isFinite(seconds) ? Date.now() + seconds * 1_000 : Date.parse(error.retryAfter);
+            if (Number.isFinite(until))
+                delay = Math.max(delay, until - Date.now());
+        }
+        return Date.now() + delay;
+    }
+}

package/src/saas/saas-client.d.ts

@@ -0,0 +1,86 @@
+import type { ProxyRequestInput, ProxyResponse } from "../core/types.ts";
+import type { ManagedProject } from "../server/storage/saas-project-store.ts";
+export interface SaasProviderConfig {
+    id: string;
+    service: string;
+    displayName: string;
+    callbackUrl: string;
+    effectiveScopes: string[];
+    actionIds: string[];
+    proxyAvailable: boolean;
+}
+export interface SaasDiscovery {
+    projectId: string;
+    providerConfigs: SaasProviderConfig[];
+}
+export interface SaasAccount extends SaasAccountSelector {
+    projectId: string;
+    service: string;
+    alias: string | null;
+    status: "active" | "reauth_required" | "error" | "disconnected";
+    providerAccountId: string | null;
+    accountLabel: string | null;
+    scopes: string[];
+}
+export interface SaasConnectionRequest {
+    id: string;
+    status: "initiated" | "connected" | "failed" | "expired";
+    projectId: string;
+    providerConfigId: string;
+    externalUserId: string;
+    service: string;
+    alias: string | null;
+    authorizationUrl: string;
+    connectedAccountId: string | null;
+    errorCode: string | null;
+    errorMessage: string | null;
+    expiresAt: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare class SaasError extends Error {
+    readonly code: string;
+    readonly status: 400 | 402 | 403 | 404 | 409 | 413 | 429 | 500 | 501 | 502 | 503 | 504;
+    readonly retryAfter?: string;
+    readonly reason?: string;
+    connectionRequestId?: string;
+    remoteExecutionId?: string;
+    constructor(code: string, message: string, status?: SaasError["status"], retryAfter?: string, reason?: string);
+}
+export interface SaasAccountSelector {
+    providerConfigId: string;
+    externalUserId: string;
+    connectedAccountId: string;
+}
+export interface SaasLinkInput {
+    providerConfigId: string;
+    externalUserId: string;
+    alias: string;
+    returnUri: string;
+}
+export interface SaasActionResult {
+    executionId: string;
+    actionId: string;
+    output: unknown;
+}
+export interface SaasProxyResult {
+    executionId: string;
+    response: ProxyResponse;
+}
+/** Reject values that the project proxy protocol cannot represent before any remote request. */
+export declare function parseSaasProxyRequest(input: unknown): Promise<ProxyRequestInput>;
+/** The project API never supplies credentials to the local provider runtime. */
+export declare class SaasClient {
+    private readonly fetcher?;
+    constructor(fetcher?: typeof fetch);
+    discover(project: Pick<ManagedProject, "baseUrl" | "apiKey">, signal?: AbortSignal): Promise<SaasDiscovery>;
+    getAccount(project: ManagedProject, selector: SaasAccountSelector, service: string, signal?: AbortSignal): Promise<SaasAccount>;
+    getRequest(project: ManagedProject, id: string, signal?: AbortSignal): Promise<SaasConnectionRequest>;
+    createLink(project: ManagedProject, input: SaasLinkInput, signal?: AbortSignal): Promise<SaasConnectionRequest>;
+    deleteAccount(project: ManagedProject, selector: SaasAccountSelector, signal?: AbortSignal): Promise<void>;
+    executeAction(project: ManagedProject, selector: SaasAccountSelector, actionId: string, input: unknown, signal?: AbortSignal): Promise<SaasActionResult>;
+    executeProxy(project: ManagedProject, selector: SaasAccountSelector, service: string, request: ProxyRequestInput, signal?: AbortSignal): Promise<SaasProxyResult>;
+    private request;
+    private requestEnvelope;
+}
+export declare function normalizeSaasBaseUrl(value: string): string;