@oomol-lab/open-connector 1.7.0 → 1.9.0

package/src/server/storage/{sqlite-runtime-store.js → sqlite/runtime-store.js}

@@ -1,16 +1,22 @@
 import { DatabaseSync } from "node:sqlite";
-import { parseRuntimeActionHttpResult } from "../api/runtime-api.js";
-import { PlainTextSecretCodec } from "../secrets/secret-codec-core.js";
-import { ConnectionRequestStore } from "./connection-request-store.js";
-import { defaultMigrationSource } from "./migration-source.js";
-import { listRunLogs, parseJson, readRunLogRow, readRuntimePolicyRow, readRuntimeTokenRow, readString, runtimeTokenColumns, } from "./runtime-sql.js";
-import { DEFAULT_RUN_LIMIT } from "./runtime-store.js";
+import { parseRuntimeActionHttpResult } from "../../api/runtime-api.js";
+import { PlainTextSecretCodec } from "../../secrets/secret-codec-core.js";
+import { ConnectionRequestStore } from "../connection-request-store.js";
+import { SqlConnectionStore } from "../connection-store.js";
+import { defaultMigrationSource } from "../migration-source.js";
+import { SqlOAuthStateStore } from "../oauth-state-store.js";
+import { listRunLogs, parseJson, readRunLogRow, readRuntimePolicyRow, readRuntimeTokenRow, readString, runtimeTokenColumns, } from "../runtime-sql.js";
+import { DEFAULT_RUN_LIMIT } from "../runtime-store.js";
+import { SaasProjectStore } from "../saas-project-store.js";
+import { SqlTriggerStore } from "../trigger-store.js";
 /**
  * Shared SQLite connection for local runtime state.
  */
 export class SqliteRuntimeDatabase {
+    saasProjectStore;
     connectionRequestStore;
     connectionStore;
+    triggerStore;
     oauthClientConfigStore;
     oauthStateStore;
     runtimeTokenStore;
@@ -24,10 +30,13 @@ export class SqliteRuntimeDatabase {
         this.database = new DatabaseSync(filename);
         this.secretCodec = options.secretCodec ?? new PlainTextSecretCodec();
         this.initialize(options.migrations ?? defaultMigrationSource, options.logger);
-        this.connectionRequestStore = new ConnectionRequestStore(async (statements) => runInTransaction(this.database, () => statements.map(({ sql, values }) => this.database.prepare(sql).all(...values))), this.secretCodec);
-        this.connectionStore = new SqliteConnectionStore(this.database, this.secretCodec);
+        const transaction = async (statements) => runInTransaction(this.database, () => statements.map(({ sql, values }) => this.database.prepare(sql).all(...values)));
+        this.connectionRequestStore = new ConnectionRequestStore(transaction, this.secretCodec);
+        this.connectionStore = new SqlConnectionStore(transaction, this.secretCodec);
+        this.triggerStore = new SqlTriggerStore(transaction, this.secretCodec);
+        this.saasProjectStore = new SaasProjectStore(transaction, this.secretCodec);
         this.oauthClientConfigStore = new SqliteOAuthClientConfigStore(this.database, this.secretCodec);
-        this.oauthStateStore = new SqliteOAuthStateStore(this.database, this.secretCodec);
+        this.oauthStateStore = new SqlOAuthStateStore(transaction, this.secretCodec);
         this.runtimeTokenStore = new SqliteRuntimeTokenStore(this.database);
         this.runtimePolicyStore = new SqliteRuntimePolicyStore(this.database);
         this.runLogStore = new SqliteRunLogStore(this.database, options.runLimit ?? DEFAULT_RUN_LIMIT);
@@ -38,25 +47,63 @@ export class SqliteRuntimeDatabase {
         this.database.close();
     }
     async rotateSecretCodec(nextSecretCodec) {
-        const connections = await readRotatedConnectionSecrets(this.database, this.secretCodec, nextSecretCodec);
-        const oauthConfigs = await readRotatedServiceSecrets(this.database, this.secretCodec, nextSecretCodec, "oauth_client_configs");
-        const requestSecrets = await Promise.all(this.database
-            .prepare("select id, value from connection_requests where value is not null")
-            .all()
-            .map(async (row) => ({
-            id: readString(row, "id"),
-            value: await nextSecretCodec.encode(await this.secretCodec.decode(readString(row, "value"))),
-        })));
-        const oauthStates = await readRotatedStateSecrets(this.database, this.secretCodec, nextSecretCodec);
-        const idempotencyResponses = await readRotatedIdempotencySecrets(this.database, this.secretCodec, nextSecretCodec);
-        const marketplaceConfig = await this.marketplaceStore.getConfig();
-        const rotatedMarketplaceConfig = marketplaceConfig
-            ? {
-                ...marketplaceConfig,
-                apiKeyEncrypted: await nextSecretCodec.encode(await this.secretCodec.decode(marketplaceConfig.apiKeyEncrypted)),
-            }
-            : undefined;
-        runInTransaction(this.database, () => {
+        this.database.exec("begin immediate");
+        try {
+            const project = this.database.prepare("select value from managed_project where id = 1").get();
+            if (project && !nextSecretCodec.encrypted)
+                throw new Error("SaaS project configuration requires encrypted storage.");
+            const projectValue = project
+                ? await nextSecretCodec.encode(await this.secretCodec.decode(readString(project, "value")))
+                : undefined;
+            const candidates = await Promise.all(this.database
+                .prepare("select id, candidate_value from connection_requests where candidate_value is not null")
+                .all()
+                .map(async (row) => ({
+                id: readString(row, "id"),
+                value: await nextSecretCodec.encode(await this.secretCodec.decode(readString(row, "candidate_value"))),
+            })));
+            const returnUris = await Promise.all(this.database
+                .prepare("select id, return_uri from connection_requests where return_uri is not null")
+                .all()
+                .map(async (row) => ({
+                id: readString(row, "id"),
+                value: await nextSecretCodec.encode(await this.secretCodec.decode(readString(row, "return_uri"))),
+            })));
+            const triggerSecrets = await Promise.all(this.database
+                .prepare("select id, value from trigger_subscriptions")
+                .all()
+                .map(async (row) => ({
+                id: readString(row, "id"),
+                value: await nextSecretCodec.encode(await this.secretCodec.decode(readString(row, "value"))),
+            })));
+            const connections = await readRotatedConnectionSecrets(this.database, this.secretCodec, nextSecretCodec);
+            const oauthConfigs = await readRotatedServiceSecrets(this.database, this.secretCodec, nextSecretCodec, "oauth_client_configs");
+            const requestSecrets = await Promise.all(this.database
+                .prepare("select id, value from connection_requests where value is not null")
+                .all()
+                .map(async (row) => ({
+                id: readString(row, "id"),
+                value: await nextSecretCodec.encode(await this.secretCodec.decode(readString(row, "value"))),
+            })));
+            const oauthStates = await readRotatedStateSecrets(this.database, this.secretCodec, nextSecretCodec);
+            const idempotencyResponses = await readRotatedIdempotencySecrets(this.database, this.secretCodec, nextSecretCodec);
+            const marketplaceConfig = await this.marketplaceStore.getConfig();
+            const rotatedMarketplaceConfig = marketplaceConfig
+                ? {
+                    ...marketplaceConfig,
+                    apiKeyEncrypted: await nextSecretCodec.encode(await this.secretCodec.decode(marketplaceConfig.apiKeyEncrypted)),
+                }
+                : undefined;
+            if (projectValue)
+                this.database.prepare("update managed_project set value = ? where id = 1").run(projectValue);
+            for (const candidate of candidates)
+                this.database
+                    .prepare("update connection_requests set candidate_value = ? where id = ?")
+                    .run(candidate.value, candidate.id);
+            for (const uri of returnUris)
+                this.database.prepare("update connection_requests set return_uri = ? where id = ?").run(uri.value, uri.id);
+            for (const record of triggerSecrets)
+                this.database.prepare("update trigger_subscriptions set value = ? where id = ?").run(record.value, record.id);
             writeRotatedConnectionSecrets(this.database, connections);
             writeRotatedServiceSecrets(this.database, "oauth_client_configs", oauthConfigs);
             writeRotatedStateSecrets(this.database, oauthStates);
@@ -70,10 +117,21 @@ export class SqliteRuntimeDatabase {
                     .prepare("update marketplace_config set value = ? where id = 1")
                     .run(JSON.stringify(rotatedMarketplaceConfig));
             }
-        });
+            this.database.exec("commit");
+        }
+        catch (error) {
+            this.database.exec("rollback");
+            throw error;
+        }
     }
     resetRuntimeData() {
-        this.database.exec(`
+        runInTransaction(this.database, () => {
+            this.database.prepare("update connection_retirements set generation = ?").run(crypto.randomUUID());
+            this.database.exec(`
+      delete from oauth_sources;
+      delete from saas_cleanup;
+      delete from managed_project;
+      delete from trigger_subscriptions;
       delete from connections;
       delete from oauth_client_configs;
       delete from oauth_states;
@@ -85,6 +143,7 @@ export class SqliteRuntimeDatabase {
       delete from marketplace_config;
       delete from provider_preferences;
     `);
+        });
     }
     initialize(migrations, logger) {
         this.database.exec("pragma journal_mode = wal;");
@@ -125,79 +184,6 @@ export class SqliteMarketplaceStore {
             .run(preference.service, preference.enabled ? 1 : 0, preference.createdAt, preference.updatedAt);
     }
 }
-export class SqliteConnectionStore {
-    database;
-    secretCodec;
-    constructor(database, secretCodec) {
-        this.database = database;
-        this.secretCodec = secretCodec;
-    }
-    async get(service, connectionName) {
-        const row = this.database
-            .prepare("select id, revision, value from connections where service = ? and connection_name = ?")
-            .get(service, connectionName);
-        return row
-            ? {
-                id: readString(row, "id"),
-                revision: readString(row, "revision"),
-                service,
-                connectionName,
-                credential: parseJson(await this.secretCodec.decode(readString(row, "value"))),
-            }
-            : undefined;
-    }
-    async set(service, connectionName, credential) {
-        const row = this.database
-            .prepare(`
-        insert into connections (id, revision, service, connection_name, value, updated_at)
-        values (?, ?, ?, ?, ?, ?)
-        on conflict(service, connection_name) do update set
-          revision = excluded.revision,
-          value = excluded.value,
-          updated_at = excluded.updated_at
-        returning id, revision
-      `)
-            .get(crypto.randomUUID(), crypto.randomUUID(), service, connectionName, await this.secretCodec.encode(JSON.stringify(credential)), new Date().toISOString());
-        if (!row) {
-            throw new Error("Connection upsert did not return the stored row.");
-        }
-        return {
-            id: readString(row, "id"),
-            revision: readString(row, "revision"),
-            service,
-            connectionName,
-            credential,
-        };
-    }
-    async updateCredential(input) {
-        const row = this.database
-            .prepare(`
-        update connections
-        set revision = ?, value = ?, updated_at = ?
-        where service = ? and connection_name = ? and id = ? and revision = ?
-        returning id
-      `)
-            .get(crypto.randomUUID(), await this.secretCodec.encode(JSON.stringify(input.credential)), new Date().toISOString(), input.service, input.connectionName, input.id, input.revision);
-        return row !== undefined;
-    }
-    async delete(service, connectionName) {
-        this.database
-            .prepare("delete from connections where service = ? and connection_name = ?")
-            .run(service, connectionName);
-    }
-    async list() {
-        const rows = this.database
-            .prepare("select id, revision, service, connection_name, value from connections order by service, connection_name")
-            .all();
-        return await Promise.all(rows.map(async (row) => ({
-            id: readString(row, "id"),
-            revision: readString(row, "revision"),
-            service: readString(row, "service"),
-            connectionName: readString(row, "connection_name"),
-            credential: parseJson(await this.secretCodec.decode(readString(row, "value"))),
-        })));
-    }
-}
 export class SqliteOAuthClientConfigStore {
     database;
     secretCodec;
@@ -230,35 +216,10 @@ export class SqliteOAuthClientConfigStore {
         return await Promise.all(rows.map(async (row) => parseJson(await this.secretCodec.decode(readString(row, "value")))));
     }
 }
-export class SqliteOAuthStateStore {
-    database;
-    secretCodec;
-    constructor(database, secretCodec) {
-        this.database = database;
-        this.secretCodec = secretCodec;
-    }
-    async deleteCreatedBefore(cutoff) {
-        this.database.prepare("delete from oauth_states where created_at < ?").run(cutoff);
-    }
-    async set(state) {
-        this.database
-            .prepare(`
-        insert into oauth_states (state, value, created_at)
-        values (?, ?, ?)
-        on conflict(state) do update set value = excluded.value, created_at = excluded.created_at
-      `)
-            .run(state.state, await this.secretCodec.encode(JSON.stringify(state)), state.createdAt);
-    }
-    async take(state) {
-        const row = this.database.prepare("select value from oauth_states where state = ?").get(state);
-        this.database.prepare("delete from oauth_states where state = ?").run(state);
-        return row
-            ? parseJson(await this.secretCodec.decode(readString(row, "value")))
-            : undefined;
-    }
-}
 export class SqliteRuntimeTokenStore {
     database;
+    findByHashStatement;
+    markUsedStatement;
     constructor(database) {
         this.database = database;
     }
@@ -268,9 +229,9 @@ export class SqliteRuntimeTokenStore {
         insert into runtime_tokens (
           ${runtimeTokenColumns}
         )
-        values (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `)
-            .run(record.id, record.name, record.tokenHash, JSON.stringify(record.allowedActions), JSON.stringify(record.blockedActions), JSON.stringify(record.allowedProxies), JSON.stringify(record.allowedConnections ?? []), record.createdAt, record.lastUsedAt ?? null);
+            .run(record.id, record.name, record.tokenHash, JSON.stringify(record.allowedActions), JSON.stringify(record.blockedActions), JSON.stringify(record.allowedProxies), JSON.stringify(record.allowedConnections ?? []), JSON.stringify(record.allowedTriggers ?? []), record.createdAt, record.lastUsedAt ?? null);
     }
     async list() {
         return this.database
@@ -283,24 +244,24 @@ export class SqliteRuntimeTokenStore {
             .map(readRuntimeTokenRow);
     }
     async findByHash(tokenHash) {
-        const row = this.database
-            .prepare(`
-        select ${runtimeTokenColumns}
-        from runtime_tokens
-        where token_hash = ?
-      `)
-            .get(tokenHash);
+        // Custom migration sources may omit this table until the store is actually used.
+        this.findByHashStatement ??= this.database.prepare(`
+      select ${runtimeTokenColumns}
+      from runtime_tokens
+      where token_hash = ?
+    `);
+        const row = this.findByHashStatement.get(tokenHash);
         return row ? readRuntimeTokenRow(row) : undefined;
     }
     async updatePolicy(id, policy) {
         const row = this.database
             .prepare(`
         update runtime_tokens
-        set allowed_actions = ?, blocked_actions = ?, allowed_proxies = ?, allowed_connections = ?
+        set allowed_actions = ?, blocked_actions = ?, allowed_proxies = ?, allowed_connections = ?, allowed_triggers = ?
         where id = ?
         returning ${runtimeTokenColumns}
       `)
-            .get(JSON.stringify(policy.allowedActions), JSON.stringify(policy.blockedActions), JSON.stringify(policy.allowedProxies), JSON.stringify(policy.allowedConnections ?? []), id);
+            .get(JSON.stringify(policy.allowedActions), JSON.stringify(policy.blockedActions), JSON.stringify(policy.allowedProxies), JSON.stringify(policy.allowedConnections ?? []), JSON.stringify(policy.allowedTriggers ?? []), id);
         return row ? readRuntimeTokenRow(row) : undefined;
     }
     async revoke(id) {
@@ -308,7 +269,8 @@ export class SqliteRuntimeTokenStore {
         return result.changes > 0;
     }
     async markUsed(id, usedAt) {
-        this.database.prepare("update runtime_tokens set last_used_at = ? where id = ?").run(usedAt, id);
+        this.markUsedStatement ??= this.database.prepare("update runtime_tokens set last_used_at = ? where id = ?");
+        this.markUsedStatement.run(usedAt, id);
     }
 }
 export class SqliteRuntimePolicyStore {

package/src/server/storage/trigger-store.d.ts

@@ -0,0 +1,16 @@
+import type { TriggerSubscription, TriggerStore } from "../../triggers/store.ts";
+import type { ISecretCodec } from "../secrets/secret-codec-core.ts";
+import type { RequestTransaction } from "./connection-request-store.ts";
+export declare class SqlTriggerStore implements TriggerStore {
+    private readonly transaction;
+    private readonly codec;
+    constructor(transaction: RequestTransaction, codec: ISecretCodec);
+    private read;
+    list(): Promise<TriggerSubscription[]>;
+    listFlowTriggersForMaintenance(now: number, limit: number): Promise<TriggerSubscription[]>;
+    getFlowTrigger(id: string): Promise<TriggerSubscription | null>;
+    insertFlowTrigger(record: TriggerSubscription): Promise<TriggerSubscription>;
+    claimFlowTrigger(id: string, owner: string, now: number, until: number): Promise<boolean>;
+    saveFlowTrigger(record: TriggerSubscription, owner: string, now: number): Promise<boolean>;
+    releaseFlowTrigger(id: string, owner: string): Promise<void>;
+}

package/src/server/storage/trigger-store.js

@@ -0,0 +1,96 @@
+import { HttpRequestError } from "../api/http-utils.js";
+export class SqlTriggerStore {
+    transaction;
+    codec;
+    constructor(transaction, codec) {
+        this.transaction = transaction;
+        this.codec = codec;
+    }
+    async read(row) {
+        return JSON.parse(await this.codec.decode(row.value));
+    }
+    async list() {
+        const [rows] = await this.transaction([{ sql: "select value from trigger_subscriptions order by id", values: [] }]);
+        return Promise.all(rows.map((row) => this.read(row)));
+    }
+    async listFlowTriggersForMaintenance(now, limit) {
+        const [rows] = await this.transaction([
+            {
+                sql: `select value from trigger_subscriptions where mode <> 'resource-set'
+      and status in ('active', 'deleting') and maintenance_at <= ? and (lease_until is null or lease_until <= ?)
+      order by maintenance_at, id limit ?`,
+                values: [now, now, limit],
+            },
+        ]);
+        return Promise.all(rows.map((row) => this.read(row)));
+    }
+    async getFlowTrigger(id) {
+        const [[row]] = await this.transaction([
+            { sql: "select value from trigger_subscriptions where id = ?", values: [id] },
+        ]);
+        return row ? this.read(row) : null;
+    }
+    async insertFlowTrigger(record) {
+        const value = await this.codec.encode(JSON.stringify(record));
+        const [, , [row]] = await this.transaction([
+            {
+                sql: "update connections set revision = revision where id = ? and revision = ? and source = 'local' returning id",
+                values: [record.connectionId, record.connectionRevision],
+            },
+            { sql: "update runtime_tokens set name = name where id = ? returning id", values: [record.tokenId] },
+            {
+                sql: `insert into trigger_subscriptions (id, mode, token_id, connection_id, trigger_id, status, reconcile_at, value)
+        select ?, ?, ?, ?, ?, ?, ?, ? where exists (select 1 from connections where id = ? and revision = ? and source = 'local')
+        and (? = 'resource-set' or exists (select 1 from runtime_tokens where id = ?))
+        on conflict (id) do nothing returning value`,
+                values: [
+                    record.id,
+                    record.mode,
+                    record.tokenId,
+                    record.connectionId,
+                    record.triggerId,
+                    record.status,
+                    record.reconcileAt,
+                    value,
+                    record.connectionId,
+                    record.connectionRevision,
+                    record.mode,
+                    record.tokenId,
+                ],
+            },
+        ]);
+        const existing = row ? await this.read(row) : await this.getFlowTrigger(record.id);
+        if (!existing)
+            throw new HttpRequestError("trigger_connection_error", "The connection or runtime token changed while creating the subscription.", 409);
+        return existing;
+    }
+    async claimFlowTrigger(id, owner, now, until) {
+        const [[row]] = await this.transaction([
+            {
+                sql: `update trigger_subscriptions set lease_owner = ?, lease_until = ?
+      where id = ? and (lease_until is null or lease_until <= ?) returning id`,
+                values: [owner, until, id, now],
+            },
+        ]);
+        return !!row;
+    }
+    async saveFlowTrigger(record, owner, now) {
+        const value = await this.codec.encode(JSON.stringify(record));
+        const [[row]] = await this.transaction([
+            {
+                sql: `update trigger_subscriptions set status = ?, reconcile_at = ?, maintenance_at = ?, value = ?
+      where id = ? and lease_owner = ? and lease_until > ? returning id`,
+                values: [record.status, record.reconcileAt, now + 60_000, value, record.id, owner, now],
+            },
+        ]);
+        return !!row;
+    }
+    async releaseFlowTrigger(id, owner) {
+        await this.transaction([
+            {
+                sql: "update trigger_subscriptions set lease_owner = null, lease_until = null where id = ? and lease_owner = ?",
+                values: [id, owner],
+            },
+        ]);
+    }
+}

package/src/triggers/common/config.d.ts

@@ -0,0 +1,2 @@
+import type { Group, InputPort, JsonValue } from "./types.ts";
+export declare function resolveTriggerConfig(inputs: readonly (InputPort | Group)[], config: Readonly<Record<string, JsonValue>>, partial?: boolean): Readonly<Record<string, JsonValue>>;

package/src/triggers/common/config.js

@@ -0,0 +1,17 @@
+import { Validator } from "@cfworker/json-schema";
+import { HttpRequestError } from "../../server/api/http-utils.js";
+export function resolveTriggerConfig(inputs, config, partial = false) {
+    const fields = inputs.filter((input) => "handle" in input);
+    const known = new Set(fields.map((field) => field.handle));
+    if (Object.keys(config).some((key) => !known.has(key)))
+        throw new HttpRequestError("invalid_input", "Unknown Trigger configuration field.", 400);
+    return Object.fromEntries(fields
+        .filter((field) => !partial || config[field.handle] !== undefined || field.value !== undefined)
+        .map((field) => {
+        const value = config[field.handle] !== undefined ? config[field.handle] : (field.value ?? null);
+        if (!(value === null && field.nullable) &&
+            !new Validator(field.jsonSchema, "2020-12").validate(value).valid)
+            throw new HttpRequestError("invalid_input", `Invalid Trigger configuration: ${field.handle}`, 400);
+        return [field.handle, value];
+    }));
+}

package/src/triggers/common/configOptions.d.ts

@@ -0,0 +1,13 @@
+import type { ConnectorProxy } from "./proxy.ts";
+import type { JsonValue } from "./types.ts";
+export interface TriggerConfigOption {
+    readonly value: string;
+    readonly label: string;
+    readonly color?: string;
+}
+export interface TriggerConfigOptionsContext {
+    readonly field: string;
+    readonly config: Readonly<Record<string, JsonValue>>;
+    readonly connector: ConnectorProxy;
+    readonly signal?: AbortSignal;
+}

package/src/triggers/common/configOptions.js

@@ -0,0 +1 @@
+export {};

package/src/triggers/common/encoding.d.ts

@@ -0,0 +1,3 @@
+import type { JsonValue } from "./types.ts";
+export declare function canonicalJsonBytes(value: JsonValue): Uint8Array;
+export declare function digestBytes(bytes: Uint8Array): Promise<string>;

package/src/triggers/common/encoding.js

@@ -0,0 +1,19 @@
+import { sha256Hex } from "../../core/aws-sigv4.js";
+const encoder = new TextEncoder();
+function canonicalText(value) {
+    if (value == null || typeof value == "boolean" || typeof value == "string" || typeof value == "number")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalText).join(",")}]`;
+    const object = value;
+    return `{${Object.keys(object)
+        .toSorted()
+        .map((key) => `${JSON.stringify(key)}:${canonicalText(object[key])}`)
+        .join(",")}}`;
+}
+export function canonicalJsonBytes(value) {
+    return encoder.encode(canonicalText(value));
+}
+export async function digestBytes(bytes) {
+    return `sha256:${sha256Hex(bytes)}`;
+}

package/src/triggers/common/integration.d.ts

@@ -0,0 +1,115 @@
+import type { TriggerConfigOption, TriggerConfigOptionsContext } from "./configOptions.ts";
+import type { ConnectorProxyRequest, ConnectorProxyResult, ConnectorProxy } from "./proxy.ts";
+import type { IntegrationEndpointMethod, JsonValue, TriggerKeySnapshot } from "./types.ts";
+export declare const maximumIntegrationBodyBytes: number;
+export declare const maximumIntegrationDeliveryPages = 5;
+export interface ListenerReadContext {
+    readonly checkpoint: JsonValue;
+    readonly config: Readonly<Record<string, JsonValue>>;
+    readonly connector: ConnectorProxy;
+    readonly now: Date;
+    readonly signal?: AbortSignal;
+}
+export interface ListenerPage {
+    readonly checkpoint: JsonValue;
+    readonly dedupeKey: string;
+    readonly hasMore: boolean;
+    readonly outputs: Readonly<Record<string, JsonValue>> | null;
+}
+export interface ListenerSource {
+    readonly intervalMs: number;
+    readonly read: (context: ListenerReadContext) => Promise<ListenerPage>;
+}
+export declare function validateListenerPage(value: unknown): asserts value is ListenerPage;
+export type IntegrationReceiveResult = {
+    readonly outcome: "wake";
+} | {
+    readonly checkpoint?: JsonValue;
+    readonly continue?: boolean;
+    readonly dedupeKey?: string;
+    readonly outcome: "event";
+    readonly outputs: Readonly<Record<string, JsonValue>>;
+} | {
+    readonly checkpoint?: JsonValue;
+    readonly continue?: boolean;
+    readonly outcome: "ignored";
+    readonly reason: string;
+} | {
+    readonly body: string;
+    readonly contentType: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly outcome: "respond";
+    readonly status: number;
+};
+export interface IntegrationStateContext {
+    readonly checkpoint: JsonValue;
+    readonly subscription: Readonly<Record<string, JsonValue>>;
+    readonly saveCheckpoint: (checkpoint: JsonValue) => Promise<void>;
+    readonly saveSubscription: (subscription: Readonly<Record<string, JsonValue>>, reconcileAt: Date) => Promise<void>;
+}
+export interface IntegrationReceiveContext {
+    readonly eventSourceId?: string;
+    readonly signal?: AbortSignal;
+    readonly admit: boolean;
+    readonly allow?: () => Promise<boolean>;
+    readonly bindingId: string;
+    readonly callbackSecret: string;
+    readonly config: Readonly<Record<string, JsonValue>>;
+    readonly connector: ConnectorProxy;
+    readonly current: boolean;
+    readonly header: (name: string) => string | undefined;
+    readonly method: IntegrationEndpointMethod;
+    readonly now: Date;
+    readonly payload: JsonValue;
+    readonly query: (name: string) => string | undefined;
+    readonly rawBody: Uint8Array;
+    readonly state?: IntegrationStateContext;
+}
+export interface IntegrationReconcileContext {
+    readonly active: boolean;
+    readonly callbackSecret: string;
+    readonly config: Readonly<Record<string, JsonValue>>;
+    readonly connector: ConnectorProxy;
+    readonly endpointUrl: string;
+    readonly idempotencyKey: string;
+    readonly now: Date;
+    readonly signal?: AbortSignal;
+    readonly state?: IntegrationStateContext;
+}
+export interface IntegrationReconcileResult {
+    readonly outcome: "pending" | "ready";
+}
+export interface ResourceSubscription {
+    readonly key: string;
+    readonly subscribe: ConnectorProxyRequest;
+    readonly unsubscribe: ConnectorProxyRequest;
+    readonly inspect?: ConnectorProxyRequest;
+}
+export interface ResourceDefinition {
+    readonly subscriptions: (config: Readonly<Record<string, JsonValue>>) => readonly ResourceSubscription[];
+    readonly response: (result: ConnectorProxyResult) => Readonly<Record<string, JsonValue>>;
+}
+export interface IntegrationDefinition {
+    readonly resources?: ResourceDefinition;
+    readonly eventSource?: "feishu";
+    readonly configOptions?: (context: TriggerConfigOptionsContext) => Promise<readonly TriggerConfigOption[]>;
+    readonly listener?: ListenerSource;
+    readonly initialState?: {
+        readonly checkpoint: JsonValue;
+        readonly subscription: Readonly<Record<string, JsonValue>>;
+    };
+    readonly receive: (context: IntegrationReceiveContext) => IntegrationReceiveResult | Promise<IntegrationReceiveResult>;
+    readonly reconcile: (context: IntegrationReconcileContext) => Promise<IntegrationReconcileResult>;
+    readonly snapshot: TriggerKeySnapshot & {
+        readonly type: "integration";
+    };
+}
+export declare class IntegrationConnectionError extends Error {
+    readonly name = "IntegrationConnectionError";
+}
+export declare class PermanentIntegrationError extends Error {
+    readonly name = "PermanentIntegrationError";
+}
+export declare class TransientIntegrationError extends Error {
+    readonly name = "TransientIntegrationError";
+}

package/src/triggers/common/integration.js

@@ -0,0 +1,31 @@
+import { isJsonObject, isJsonValue } from "./json.js";
+export const maximumIntegrationBodyBytes = 64 * 1024;
+export const maximumIntegrationDeliveryPages = 5;
+const encoder = new TextEncoder();
+export function validateListenerPage(value) {
+    if (!isJsonObject(value) ||
+        value.checkpoint == null ||
+        !isJsonValue(value.checkpoint) ||
+        typeof value.hasMore != "boolean") {
+        throw new TypeError("Listener page must contain a JSON checkpoint and a boolean hasMore.");
+    }
+    if (typeof value.dedupeKey != "string" ||
+        value.dedupeKey.length == 0 ||
+        encoder.encode(value.dedupeKey).byteLength > 1024) {
+        throw new TypeError("Listener page identity must contain between 1 and 1024 bytes.");
+    }
+    if (value.outputs !== null && !isJsonObject(value.outputs))
+        throw new TypeError("Listener page outputs must be an object or null.");
+    if (encoder.encode(JSON.stringify(value.checkpoint)).byteLength > 64 * 1024) {
+        throw new TypeError("Listener checkpoint exceeds 64 KiB.");
+    }
+}
+export class IntegrationConnectionError extends Error {
+    name = "IntegrationConnectionError";
+}
+export class PermanentIntegrationError extends Error {
+    name = "PermanentIntegrationError";
+}
+export class TransientIntegrationError extends Error {
+    name = "TransientIntegrationError";
+}