@oomol-lab/open-connector 1.9.0 → 1.9.2

package/src/providers/humor_api/actions.js

@@ -0,0 +1,96 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+const rating = s.number("Minimum content rating from 0 to 10.", { minimum: 0, maximum: 10 });
+const pagination = {
+    offset: s.integer("Number of results to skip, from 0 to 1000.", { minimum: 0, maximum: 1000 }),
+    number: s.integer("Number of results to return, from 0 to 10.", { minimum: 0, maximum: 10 }),
+};
+const jokeFilters = {
+    "include-tags": s.string("Comma-separated tags that jokes should have."),
+    "exclude-tags": s.string("Comma-separated tags that jokes must not have."),
+    "min-rating": rating,
+    "max-length": s.integer("Maximum joke length in letters."),
+};
+const memeFilters = {
+    keywords: s.string("Comma-separated words that must occur in the meme."),
+    "keywords-in-image": s.boolean("Whether keywords must occur in the image."),
+    "media-type": s.string("Media type such as image, video, jpg, png, or gif."),
+    "min-rating": rating,
+    "max-age-days": s.integer("Maximum meme age in days."),
+};
+const joke = s.looseObject("A joke returned by Humor API.", {
+    id: s.integer("Joke identifier."),
+    joke: s.string("Joke text."),
+});
+const meme = s.looseObject("A meme returned by Humor API.", {
+    id: s.integer("Meme identifier."),
+    url: s.string("URL of the meme media."),
+    type: s.string("Media MIME type."),
+});
+export const humorApiActions = [
+    defineProviderAction("humor_api", {
+        name: "search_jokes",
+        description: "Search jokes by keywords, tags, rating, and length with offset pagination.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Joke search parameters.", {
+            keywords: s.string("Comma-separated words that must occur in the joke."),
+            ...jokeFilters,
+            ...pagination,
+        }, { optional: ["keywords", ...Object.keys(jokeFilters), ...Object.keys(pagination)] }),
+        outputSchema: s.looseObject("Joke search results.", {
+            jokes: s.array("Matching jokes.", joke),
+            available: s.integer("Total matching jokes available."),
+        }),
+    }),
+    defineProviderAction("humor_api", {
+        name: "random_joke",
+        description: "Get a random joke filtered by tags, minimum rating, and maximum length.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Random joke filters.", jokeFilters, {
+            optional: Object.keys(jokeFilters),
+        }),
+        outputSchema: joke,
+    }),
+    defineProviderAction("humor_api", {
+        name: "search_memes",
+        description: "Search memes by keywords, media type, rating, and age with offset pagination.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Meme search parameters.", { ...memeFilters, ...pagination }, {
+            optional: [...Object.keys(memeFilters), ...Object.keys(pagination)],
+        }),
+        outputSchema: s.looseObject("Meme search results.", {
+            memes: s.array("Matching memes.", meme),
+            available: s.integer("Total matching memes available."),
+        }),
+    }),
+    defineProviderAction("humor_api", {
+        name: "random_meme",
+        description: "Get a random meme filtered by keywords, media type, rating, and age.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Random meme filters.", memeFilters, {
+            optional: Object.keys(memeFilters),
+        }),
+        outputSchema: meme,
+    }),
+    defineProviderAction("humor_api", {
+        name: "search_gifs",
+        description: "Search reaction GIFs and return their URLs and dimensions.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("GIF search parameters.", {
+            query: s.nonEmptyString("Search query."),
+            number: pagination.number,
+        }, { optional: ["number"] }),
+        outputSchema: s.looseObject("GIF search results.", {
+            images: s.array("Matching GIF images.", s.looseObject("A GIF search result.", {
+                url: s.string("GIF image URL."),
+                width: s.integer("Image width in pixels."),
+                height: s.integer("Image height in pixels."),
+            })),
+        }),
+    }),
+];

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

@@ -0,0 +1,76 @@
+import { optionalRecord, optionalRawString } from "../../core/cast.js";
+import { requiredInputString, requiredResponseRecord, providerUserAgent, ProviderRequestError, runProviderRequest, defineApiKeyProviderExecutors, defineProviderProxy, mapProviderActionHandlers, readProviderProxyErrorMessage, withRetryAfterSeconds, } from "../provider-runtime.js";
+import { humorApiActions } from "./actions.js";
+const baseUrl = "https://api.humorapi.com";
+const actionPaths = {
+    search_jokes: "/jokes/search",
+    random_joke: "/jokes/random",
+    search_memes: "/memes/search",
+    random_meme: "/memes/random",
+    search_gifs: "/gif/search",
+};
+const handlers = mapProviderActionHandlers("humor_api", humorApiActions, (action) => async (dataInput, context) => {
+    const url = new URL(actionPaths[action.name], baseUrl);
+    for (const [name, value] of Object.entries(dataInput)) {
+        if (value != null)
+            url.searchParams.set(name, String(value));
+    }
+    const apiKey = context.apiKey;
+    return runProviderRequest({ signal: context.signal, label: "Humor API" }, async (signal) => {
+        const response = await context.fetcher(url, {
+            headers: {
+                "x-api-key": apiKey,
+                accept: "application/json",
+                "user-agent": providerUserAgent,
+            },
+            signal,
+        });
+        const text = await response.text();
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            if (response.ok)
+                throw new ProviderRequestError(502, "Humor API returned invalid JSON", undefined, "provider_error");
+        }
+        if (!response.ok) {
+            const body = optionalRecord(payload);
+            const message = optionalRawString(body?.message) ??
+                optionalRawString(body?.error) ??
+                `Humor API request failed (HTTP ${response.status})`;
+            throw new ProviderRequestError(response.status, message, undefined, response.status === 429 ? "rate_limited" : "provider_error");
+        }
+        return requiredResponseRecord(payload, "Humor API response");
+    });
+});
+export const executors = defineApiKeyProviderExecutors("humor_api", handlers, {
+    skipDnsValidation: true,
+});
+export const credentialValidators = {
+    async apiKey(input) {
+        requiredInputString(input.apiKey, "API Key");
+        return {
+            profile: { displayName: "Humor API Key" },
+            grantedScopes: [],
+            metadata: { apiBaseUrl: baseUrl, validationMode: "local_non_empty_key" },
+        };
+    },
+};
+export const proxy = defineProviderProxy({
+    service: "humor_api",
+    baseUrl,
+    auth: { type: "api_key_header", name: "x-api-key" },
+    skipDnsValidation: true,
+    customizeRequest({ headers }) {
+        for (const [name, value] of Object.entries({
+            accept: "application/json",
+            "user-agent": providerUserAgent,
+        }))
+            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/intercom/executors.d.ts

@@ -1,4 +1,6 @@
 import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
 export declare const executors: ProviderExecutors;
 export declare const proxy: ProviderProxyExecutor;
 export declare const credentialValidators: CredentialValidators;
+export declare const triggers: readonly IntegrationDefinition[];

package/src/providers/intercom/executors.js

@@ -1,5 +1,6 @@
 import { defineProviderExecutors, defineProviderProxy, requireOAuthCredential } from "../provider-runtime.js";
 import { intercomActionHandlers, intercomAllowedApiBaseUrls, intercomApiVersion, resolveIntercomApiBaseUrl, validateIntercomOAuthCredential, } from "./runtime.js";
+import { intercomConversationEvents } from "./trigger-on-conversation-event.js";
 const service = "intercom";
 export const executors = defineProviderExecutors({
     service,
@@ -32,3 +33,4 @@ export const credentialValidators = {
         return validateIntercomOAuthCredential(input, fetcher, signal);
     },
 };
+export const triggers = [intercomConversationEvents];

package/src/providers/intercom/trigger-on-conversation-event.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
+export declare const intercomConversationEvents: IntegrationDefinition;

package/src/providers/intercom/trigger-on-conversation-event.definition.d.ts

@@ -0,0 +1,4 @@
+import type { TriggerKeySnapshot } from "../../triggers/common/types.ts";
+export declare const snapshot: TriggerKeySnapshot & {
+    readonly type: "integration";
+};

package/src/providers/intercom/trigger-on-conversation-event.definition.js

@@ -0,0 +1,42 @@
+import { s } from "../../core/json-schema.js";
+export const snapshot = {
+    key: "intercom.on_conversation_event",
+    provider: "intercom",
+    name: "on_conversation_event",
+    displayName: "Customer Conversation or Ticket",
+    description: "Receives customer conversations, customer replies and new tickets from a verified Intercom application event source. Administrator replies are excluded.",
+    definitionVersion: 2,
+    type: "integration",
+    endpoint: {
+        methods: ["POST"],
+        body: { formats: ["json"], allowArray: false, allowEmpty: false },
+        successStatus: 200,
+    },
+    configInputs: [
+        {
+            handle: "sourceId",
+            jsonSchema: { type: "string", pattern: "^source_[0-9a-f]{32}$", title: "Event source" },
+            nullable: false,
+        },
+        {
+            handle: "eventTypes",
+            jsonSchema: {
+                type: "array",
+                items: { type: "string", enum: ["conversation.user.created", "conversation.user.replied", "ticket.created"] },
+                minItems: 1,
+                maxItems: 3,
+                uniqueItems: true,
+                title: "Events",
+            },
+            nullable: false,
+            value: ["conversation.user.created", "conversation.user.replied", "ticket.created"],
+        },
+    ],
+    outputs: [
+        { handle: "event", jsonSchema: s.string(), nullable: false },
+        { handle: "deliveryId", jsonSchema: s.string(), nullable: false },
+        { handle: "workspaceId", jsonSchema: s.string(), nullable: false },
+        { handle: "objectId", jsonSchema: s.string(), nullable: false },
+        { handle: "body", jsonSchema: s.object({}, { additionalProperties: true }), nullable: false },
+    ],
+};

package/src/providers/intercom/trigger-on-conversation-event.js

@@ -0,0 +1,23 @@
+import { PermanentIntegrationError } from "../../triggers/common/integration.js";
+import { isJsonObject } from "../../triggers/common/json.js";
+import { intercomApplication } from "../../triggers/sources/intercom.js";
+import { snapshot } from "./trigger-on-conversation-event.definition.js";
+export const intercomConversationEvents = {
+    snapshot,
+    eventSource: "intercom",
+    source: intercomApplication,
+    receive(context) {
+        if (context.eventSourceId !== context.config.sourceId)
+            return { outcome: "respond", status: 404, body: "", contentType: "text/plain" };
+        const payload = context.payload;
+        if (!isJsonObject(payload) ||
+            typeof payload.deliveryId !== "string" ||
+            !payload.deliveryId ||
+            !isJsonObject(payload.body))
+            throw new PermanentIntegrationError("Invalid shared Intercom event.");
+        return { outcome: "event", dedupeKey: payload.deliveryId, outputs: payload };
+    },
+    async reconcile() {
+        throw new PermanentIntegrationError("This deployment does not support shared Intercom event sources.");
+    },
+};

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

@@ -1,4 +1,5 @@
 import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
 import type { ProviderActionHandlers } from "../provider-runtime.ts";
 type JiraActionContext = {
     accessToken: string;
@@ -22,4 +23,5 @@ export declare const credentialValidators: CredentialValidators;
  * suffix this provider speaks, so a pasted API URL is not double-appended.
  */
 export declare function normalizeJiraServerApiBaseUrl(value: unknown, allowPrivateNetwork?: boolean): string;
+export declare const triggers: readonly IntegrationDefinition[];
 export {};

package/src/providers/jira/executors.js

@@ -1,6 +1,7 @@
 import { compactObject, optionalBoolean, optionalInteger as asOptionalInteger, optionalRecord as asOptionalObject, optionalString as asOptionalString, optionalStringArray, } from "../../core/cast.js";
 import { assertPublicHttpUrl, isPrivateNetworkAccessAllowed } from "../../core/request.js";
 import { createProviderFetch, ProviderRequestError, defineProviderExecutors, defineProviderProxy, providerUserAgent, } from "../provider-runtime.js";
+import { jiraIssueEvents } from "./trigger-on-issue-event.js";
 const jiraApiOrigin = "https://api.atlassian.com";
 const jiraAccessibleResourcesUrl = "https://api.atlassian.com/oauth/token/accessible-resources";
 const jiraCurrentUserPath = "/myself";
@@ -944,3 +945,4 @@ function trimLeadingSlash(value) {
     }
     return value.slice(index);
 }
+export const triggers = [jiraIssueEvents];

package/src/providers/jira/trigger-on-issue-event.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
+export declare const jiraIssueEvents: IntegrationDefinition;

package/src/providers/jira/trigger-on-issue-event.definition.d.ts

@@ -0,0 +1,4 @@
+import type { TriggerKeySnapshot } from "../../triggers/common/types.ts";
+export declare const snapshot: TriggerKeySnapshot & {
+    readonly type: "integration";
+};

package/src/providers/jira/trigger-on-issue-event.definition.js

@@ -0,0 +1,44 @@
+export const snapshot = {
+    key: "jira.on_issue_event",
+    provider: "jira",
+    name: "on_issue_event",
+    displayName: "Issue or Comment Event",
+    description: "Receives Jira Cloud issue creation, issue updates and new comments through a shared project webhook with automatic renewal.",
+    definitionVersion: 2,
+    type: "integration",
+    endpoint: {
+        methods: ["POST"],
+        body: { formats: ["json"], allowArray: false, allowEmpty: false },
+        successStatus: 200,
+    },
+    configInputs: [
+        {
+            handle: "sourceId",
+            jsonSchema: { type: "string", pattern: "^source_[0-9a-f]{32}$", title: "Event source" },
+            nullable: false,
+        },
+        {
+            handle: "eventTypes",
+            jsonSchema: {
+                type: "array",
+                items: {
+                    type: "string",
+                    enum: ["jira:issue_created", "jira:issue_updated", "comment_created"],
+                },
+                minItems: 1,
+                maxItems: 3,
+                uniqueItems: true,
+                title: "Events",
+            },
+            nullable: false,
+            value: ["jira:issue_created", "jira:issue_updated", "comment_created"],
+        },
+    ],
+    outputs: [
+        { handle: "event", jsonSchema: { type: "string" }, nullable: false },
+        { handle: "deliveryId", jsonSchema: { type: "string" }, nullable: false },
+        { handle: "cloudId", jsonSchema: { type: "string" }, nullable: false },
+        { handle: "issueId", jsonSchema: { type: "string" }, nullable: false },
+        { handle: "body", jsonSchema: { type: "object" }, nullable: false },
+    ],
+};

package/src/providers/jira/trigger-on-issue-event.js

@@ -0,0 +1,116 @@
+import { jwtVerify } from "jose";
+import { IntegrationConnectionError } from "../../triggers/common/integration.js";
+import { PermanentIntegrationError } from "../../triggers/common/integration.js";
+import { isJsonObject } from "../../triggers/common/json.js";
+import { webhookRequest } from "../../triggers/managed-webhook.js";
+import { jiraProject } from "../../triggers/sources/jira.js";
+import { snapshot } from "./trigger-on-issue-event.definition.js";
+import { reconcileJiraResource, requireJiraCloud, jiraEvents } from "./trigger-resource.js";
+export const jiraIssueEvents = {
+    snapshot,
+    eventSource: "jira",
+    source: jiraProject,
+    resources: { reconcile: reconcileJiraResource },
+    async sourceIdentity(context) {
+        const cloudId = requireJiraCloud(context.connector);
+        const project = context.config.projectId ?? context.config.project;
+        if (typeof project !== "string" || !project || project.length > 256)
+            throw new PermanentIntegrationError("Choose a Jira project.");
+        const [projectResult, userResult, siteResult] = await Promise.all([
+            webhookRequest(context, { method: "GET", endpoint: `/project/${encodeURIComponent(project)}` }),
+            webhookRequest(context, { method: "GET", endpoint: "/myself" }),
+            webhookRequest(context, { method: "GET", endpoint: "/serverInfo" }),
+        ]);
+        const item = projectResult.data, user = userResult.data, site = siteResult.data;
+        if (!isJsonObject(item) ||
+            typeof item.id !== "string" ||
+            !/^\d+$/.test(item.id) ||
+            typeof item.key !== "string" ||
+            !isJsonObject(user) ||
+            typeof user.accountId !== "string" ||
+            !isJsonObject(site) ||
+            typeof site.baseUrl !== "string")
+            throw new PermanentIntegrationError("Jira did not return a verified project, user and site.");
+        const url = new URL(site.baseUrl);
+        if (url.protocol !== "https:" || url.username || url.password)
+            throw new PermanentIntegrationError("Invalid Jira Cloud site URL.");
+        return {
+            accountId: context.connector.providerAccountId,
+            cloudId,
+            userId: user.accountId,
+            projectId: item.id,
+            projectKey: item.key,
+            siteUrl: url.origin,
+        };
+    },
+    async sourceReceive(context) {
+        const cloudId = requireJiraCloud(context.connector);
+        if (context.config.cloudId !== cloudId)
+            throw new IntegrationConnectionError("The Jira connection belongs to another site.");
+        const authorization = context.headers.authorization ?? "";
+        if (!authorization.startsWith("Bearer "))
+            return { outcome: "unauthorized" };
+        try {
+            await jwtVerify(authorization.slice(7), new TextEncoder().encode(context.connector.oauthClientConfig.clientSecret), { algorithms: ["HS256"], currentDate: context.now, requiredClaims: ["exp"] });
+        }
+        catch {
+            return { outcome: "unauthorized" };
+        }
+        let payload;
+        try {
+            payload = JSON.parse(context.rawBody);
+        }
+        catch {
+            return { outcome: "unauthorized" };
+        }
+        if (!isJsonObject(payload) ||
+            typeof payload.webhookEvent !== "string" ||
+            !jiraEvents.includes(payload.webhookEvent))
+            return { outcome: "ignored" };
+        if (!Array.isArray(payload.matchedWebhookIds) || !payload.matchedWebhookIds.includes(context.config.webhookId))
+            return { outcome: "ignored" };
+        const issue = payload.issue;
+        if (!isJsonObject(issue) ||
+            typeof issue.id !== "string" ||
+            typeof issue.self !== "string" ||
+            !isJsonObject(issue.fields) ||
+            !isJsonObject(issue.fields.project) ||
+            issue.fields.project.id !== context.config.projectId)
+            return { outcome: "ignored" };
+        let issueUrl;
+        try {
+            issueUrl = new URL(issue.self);
+        }
+        catch {
+            return { outcome: "ignored" };
+        }
+        if (issueUrl.origin !== context.config.siteUrl)
+            return { outcome: "ignored" };
+        const id = context.headers["x-atlassian-webhook-identifier"];
+        if (!id || id.length > 256)
+            return { outcome: "unauthorized" };
+        if (payload.webhookEvent === "comment_created" &&
+            (!isJsonObject(payload.comment) || typeof payload.comment.id !== "string"))
+            return { outcome: "unauthorized" };
+        return {
+            outcome: "event",
+            id,
+            type: payload.webhookEvent,
+            payload: { event: payload.webhookEvent, deliveryId: id, cloudId, issueId: issue.id, body: payload },
+        };
+    },
+    receive(context) {
+        if (context.eventSourceId !== context.config.sourceId)
+            return { outcome: "respond", status: 404, body: "", contentType: "text/plain" };
+        const payload = context.payload;
+        if (!isJsonObject(payload) ||
+            typeof payload.deliveryId !== "string" ||
+            !payload.deliveryId ||
+            !isJsonObject(payload.body))
+            throw new PermanentIntegrationError("Invalid shared Jira event.");
+        return { outcome: "event", dedupeKey: payload.deliveryId, outputs: payload };
+    },
+    async reconcile() {
+        throw new PermanentIntegrationError("This deployment does not support shared Jira event sources.");
+    },
+};

package/src/providers/jira/trigger-resource.d.ts

@@ -0,0 +1,4 @@
+import type { IntegrationReconcileContext, IntegrationReconcileResult } from "../../triggers/common/integration.ts";
+export declare const jiraEvents: string[];
+export declare function requireJiraCloud(connector: IntegrationReconcileContext["connector"]): string;
+export declare function reconcileJiraResource(context: IntegrationReconcileContext): Promise<IntegrationReconcileResult>;

package/src/providers/jira/trigger-resource.js

@@ -0,0 +1,141 @@
+import { IntegrationConnectionError, PermanentIntegrationError, TransientIntegrationError, } from "../../triggers/common/integration.js";
+import { isJsonObject } from "../../triggers/common/json.js";
+import { webhookRequest } from "../../triggers/managed-webhook.js";
+export const jiraEvents = ["jira:issue_created", "jira:issue_updated", "comment_created"];
+const day = 86_400_000;
+export function requireJiraCloud(connector) {
+    const cloudId = /^jira:([^:]+)(?::|$)/.exec(connector.providerAccountId ?? "")?.[1];
+    if (connector.authType !== "oauth2" || !cloudId || !connector.oauthClientConfig?.clientSecret)
+        throw new IntegrationConnectionError("Jira Cloud OAuth and the matching application client secret are required. Reconnect with webhook permissions.");
+    return cloudId;
+}
+async function webhooks(context) {
+    const items = [];
+    let startAt = 0;
+    for (;;) {
+        const { data } = await webhookRequest(context, {
+            method: "GET",
+            endpoint: "/webhook",
+            query: { startAt, maxResults: 100 },
+        });
+        if (!isJsonObject(data) || !Array.isArray(data.values) || typeof data.isLast !== "boolean")
+            throw new TransientIntegrationError("Invalid Jira webhook page.");
+        for (const item of data.values) {
+            if (!isJsonObject(item) ||
+                !Number.isSafeInteger(item.id) ||
+                Number(item.id) <= 0 ||
+                typeof item.url !== "string" ||
+                typeof item.jqlFilter !== "string" ||
+                !Array.isArray(item.events) ||
+                !item.events.every((event) => typeof event === "string") ||
+                typeof item.expirationDate !== "string")
+                throw new TransientIntegrationError("Invalid Jira webhook record.");
+            const expiresAt = Date.parse(item.expirationDate);
+            if (!Number.isFinite(expiresAt))
+                throw new TransientIntegrationError("Invalid Jira webhook expiration.");
+            items.push({
+                id: Number(item.id),
+                url: item.url,
+                jqlFilter: item.jqlFilter,
+                events: item.events,
+                expiresAt,
+            });
+        }
+        if (data.isLast)
+            return items;
+        if (data.values.length === 0 || data.startAt !== startAt)
+            throw new TransientIntegrationError("Invalid Jira webhook pagination.");
+        startAt += data.values.length;
+    }
+}
+export async function reconcileJiraResource(context) {
+    requireJiraCloud(context.connector);
+    const { projectId } = context.config;
+    if (typeof projectId !== "string" || !/^\d+$/.test(projectId))
+        throw new PermanentIntegrationError("A verified Jira project ID is required.");
+    let endpoint;
+    try {
+        endpoint = new URL(context.endpointUrl);
+    }
+    catch {
+        throw new PermanentIntegrationError("A public HTTPS callback URL is required.");
+    }
+    if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.hash)
+        throw new PermanentIntegrationError("Jira requires a public HTTPS callback without credentials or a fragment.");
+    const now = context.now.getTime();
+    const state = context.state;
+    const saved = state.subscription;
+    if (context.active &&
+        typeof saved.checkedAt === "number" &&
+        typeof saved.expiresAt === "number" &&
+        saved.checkedAt + day > now &&
+        saved.expiresAt - 7 * day > now)
+        return { outcome: "ready" };
+    const save = (value) => state.saveSubscription(value, new Date(now + day));
+    let all = await webhooks(context);
+    const own = () => {
+        const matches = all.filter((item) => item.url === endpoint.href);
+        if (matches.length > 1)
+            throw new PermanentIntegrationError("Multiple Jira webhooks use this source callback. Resolve the duplicate subscriptions before retrying.");
+        return matches[0];
+    };
+    let hook = own();
+    if (!context.active) {
+        if (hook)
+            await webhookRequest(context, { method: "DELETE", endpoint: "/webhook", body: { webhookIds: [hook.id] } });
+        else if (saved.creating === true)
+            throw new PermanentIntegrationError("Jira registration is still uncertain. Confirm the remote webhook before cleanup.", "trigger_subscription_uncertain");
+        await save({});
+        return { outcome: "ready" };
+    }
+    if (!hook) {
+        if (saved.creating === true)
+            throw new PermanentIntegrationError("Jira registration is uncertain and no matching webhook is visible. Retry after checking Jira; do not create another source.", "trigger_subscription_uncertain");
+        if (all.length >= 5)
+            throw new PermanentIntegrationError("Jira OAuth webhook quota reached: five subscriptions per application, user and site. Remove an unused subscription, then retry.", "trigger_quota_exceeded");
+        await save({ creating: true });
+        const result = await context.connector.execute({
+            method: "POST",
+            endpoint: "/webhook",
+            body: { url: endpoint.href, webhooks: [{ jqlFilter: `project = ${projectId}`, events: jiraEvents }] },
+        }, context.signal);
+        context.signal?.throwIfAborted();
+        if (result.status < 200 || result.status >= 300) {
+            if (result.status >= 400 && result.status < 500)
+                await save({});
+            const message = `Jira webhook registration failed (HTTP ${result.status}). Check OAuth scopes, callback domain and webhook quota.`;
+            if (result.status === 429 || result.status >= 500)
+                throw new TransientIntegrationError(message);
+            throw new PermanentIntegrationError(message);
+        }
+        const results = isJsonObject(result.data) ? result.data.webhookRegistrationResult : undefined;
+        if (!Array.isArray(results) || results.length !== 1 || !isJsonObject(results[0]))
+            throw new TransientIntegrationError("Jira registration returned no confirmed webhook ID.");
+        const created = results[0];
+        if (Array.isArray(created.errors) && created.errors.length) {
+            await save({});
+            throw new PermanentIntegrationError(`Jira rejected the webhook: ${created.errors.filter((value) => typeof value === "string").join("; ")}`);
+        }
+        if (!Number.isSafeInteger(created.createdWebhookId) || Number(created.createdWebhookId) <= 0)
+            throw new TransientIntegrationError("Jira registration returned no confirmed webhook ID.");
+        await save({ creating: true, webhookId: Number(created.createdWebhookId) });
+        all = await webhooks(context);
+        hook = own();
+        if (!hook || hook.id !== created.createdWebhookId)
+            throw new TransientIntegrationError("The newly registered Jira webhook is not yet visible.");
+    }
+    if (hook.jqlFilter !== `project = ${projectId}` ||
+        hook.events.length !== jiraEvents.length ||
+        !jiraEvents.every((event) => hook.events.includes(event)))
+        throw new PermanentIntegrationError("The Jira webhook no longer matches this source's project and events. Remove the source subscription before recreating it.");
+    if (hook.expiresAt - 7 * day <= now) {
+        await webhookRequest(context, { method: "PUT", endpoint: "/webhook/refresh", body: { webhookIds: [hook.id] } });
+        const previousId = hook.id;
+        all = await webhooks(context);
+        hook = own();
+        if (!hook || hook.id !== previousId || hook.expiresAt - 7 * day <= now)
+            throw new TransientIntegrationError("Jira did not confirm the renewed webhook expiration.");
+    }
+    await save({ webhookId: hook.id, expiresAt: hook.expiresAt, checkedAt: now });
+    return { outcome: "ready" };
+}

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

@@ -0,0 +1,4 @@
+import type { ActionDefinition } from "../../core/types.ts";
+import type { KaonaviActionDefinition } from "./additional-actions.ts";
+export declare const kaonaviActionDefinitions: KaonaviActionDefinition[];
+export declare const kaonaviActions: ActionDefinition[];