@automate.ax/integration-contracts 0.82.0 → 0.83.0

package/dist/convex/api.d.ts

@@ -0,0 +1,109 @@
+import type { JSONValue } from "convex/values";
+import * as z from "zod";
+import { type ConvexValue } from "./schemas.js";
+export declare const CONVEX_DEPLOYMENT_URL_SCHEMA: z.ZodURL;
+export declare const CONVEX_SECRET_SCHEMA: z.ZodUnion<readonly [z.ZodObject<{
+    accessToken: z.ZodString;
+    projectId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    deployKey: z.ZodString;
+    deploymentUrl: z.ZodURL;
+    webhookSecret: z.ZodString;
+}, z.core.$strip>]>;
+export interface ConvexDeployment {
+    deploymentUrl: string;
+    reference: string;
+    token: string;
+}
+/**
+ * Resolves the authenticated Convex deployment represented by an account.
+ *
+ * @param secret - Persisted Convex account secret.
+ * @param deployment - Default alias or explicit deployment reference.
+ */
+export declare function resolveConvexDeployment(secret: unknown, deployment?: string): Promise<ConvexDeployment>;
+/**
+ * Creates a small authenticated client for named Convex functions.
+ *
+ * @param secret - Persisted Convex account secret.
+ * @param deployment - Default alias or explicit deployment reference.
+ */
+export declare function getConvexClient(secret: unknown, deployment?: string): Promise<{
+    action: (functionName: string, arguments_?: Record<string, ConvexValue | undefined>) => Promise<ConvexValue>;
+    mutation: (functionName: string, arguments_?: Record<string, ConvexValue | undefined>) => Promise<ConvexValue>;
+    query: (functionName: string, arguments_?: Record<string, ConvexValue | undefined>) => Promise<ConvexValue>;
+}>;
+/**
+ * Runs a named Convex function through the authenticated deployment client.
+ *
+ * @param kind - Convex function kind.
+ * @param secret - Persisted Convex account secret.
+ * @param input - Function path, arguments, and deployment selection.
+ * @param input.arguments - Convex arguments keyed by parameter name.
+ * @param input.deployment - Default alias or explicit deployment reference.
+ * @param input.functionName - Exported Convex function path.
+ */
+export declare function runConvexFunction(kind: "action" | "mutation" | "query", secret: unknown, input: {
+    arguments?: Record<string, ConvexValue | undefined>;
+    deployment?: string;
+    functionName: string;
+}): Promise<ConvexValue>;
+/**
+ * Returns the deployment API token stored by either connection method.
+ *
+ * @param secret - Persisted Convex account secret.
+ */
+export declare function getConvexDeploymentToken(secret: unknown): string;
+/**
+ * Decodes Convex's tagged JSON representation into a native Convex value.
+ *
+ * @param value - Tagged JSON returned by a Convex HTTP API.
+ */
+export declare function decodeConvexValue(value: JSONValue): ConvexValue;
+/**
+ * Encodes a native Convex value into Convex's tagged JSON representation.
+ *
+ * @param value - Native Convex value to encode.
+ */
+export declare function encodeConvexValue(value: ConvexValue): JSONValue;
+/**
+ * Checks a deployment-key connection and returns provider-owned identity.
+ *
+ * @param deploymentUrl - Connected Convex deployment URL.
+ * @param token - Convex deploy key.
+ */
+export declare function getConvexDeploymentInfo(deploymentUrl: string, token: string): Promise<{
+    kind: "cloud";
+    projectId: string;
+    projectName?: string | null | undefined;
+    reference?: string | null | undefined;
+} | {
+    kind: "selfHosted";
+}>;
+export interface EmitConvexEventOptions {
+    /** Public endpoint exposed by `onConvexEvent`. */
+    endpoint: string;
+    /** Stable caller-assigned idempotency ID. */
+    id: string;
+    /** Application-defined semantic event name. */
+    name: string;
+    /** Convex-compatible payload delivered to the automation. */
+    payload: ConvexValue;
+    /** Secret configured both on the account and in Convex. */
+    signingSecret: string;
+}
+/**
+ * Emits one authenticated semantic event from a Convex action.
+ *
+ * @param options - Endpoint, identity, payload, and signing secret.
+ */
+export declare function emitConvexEvent(options: EmitConvexEventOptions): Promise<void>;
+/**
+ * Computes the portable HMAC used by Convex semantic-event requests.
+ *
+ * @param secret - Shared webhook signing secret.
+ * @param timestamp - ISO timestamp included in the signature.
+ * @param eventId - Caller-assigned idempotency ID.
+ * @param body - Exact request body.
+ */
+export declare function signConvexEvent(secret: string, timestamp: string, eventId: string, body: string): Promise<string>;

package/dist/convex/api.js

@@ -0,0 +1,214 @@
+import { convexToJson, jsonToConvex } from "convex/values";
+import * as z from "zod";
+import { CONVEX_VALUE_SCHEMA } from "./schemas.js";
+const CONVEX_OAUTH_SECRET_SCHEMA = z.object({
+    accessToken: z.string(),
+    projectId: z.string(),
+});
+export const CONVEX_DEPLOYMENT_URL_SCHEMA = z.url().refine((value) => {
+    if (!URL.canParse(value))
+        return false;
+    const url = new URL(value);
+    return (url.protocol === "https:" &&
+        url.hostname.endsWith(".convex.cloud") &&
+        url.port === "" &&
+        url.username === "" &&
+        url.password === "" &&
+        url.pathname === "/" &&
+        url.search === "" &&
+        url.hash === "");
+}, "Enter a Convex Cloud deployment URL such as https://example.convex.cloud.");
+const CONVEX_DEPLOY_KEY_SECRET_SCHEMA = z.object({
+    deployKey: z.string(),
+    deploymentUrl: CONVEX_DEPLOYMENT_URL_SCHEMA,
+    webhookSecret: z.string(),
+});
+export const CONVEX_SECRET_SCHEMA = z.union([
+    CONVEX_OAUTH_SECRET_SCHEMA,
+    CONVEX_DEPLOY_KEY_SECRET_SCHEMA,
+]);
+const CONVEX_DEPLOYMENT_SCHEMA = z.object({
+    deploymentUrl: CONVEX_DEPLOYMENT_URL_SCHEMA,
+    name: z.string(),
+    reference: z.string(),
+});
+const CONVEX_DEPLOYMENT_INFO_SCHEMA = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("cloud"),
+        projectId: z.string(),
+        projectName: z.string().nullable().optional(),
+        reference: z.string().nullable().optional(),
+    }),
+    z.object({ kind: z.literal("selfHosted") }),
+]);
+const CONVEX_FUNCTION_RESPONSE_SCHEMA = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("success"), value: z.json() }),
+    z.object({ errorMessage: z.string(), status: z.literal("error") }),
+]);
+/**
+ * Resolves the authenticated Convex deployment represented by an account.
+ *
+ * @param secret - Persisted Convex account secret.
+ * @param deployment - Default alias or explicit deployment reference.
+ */
+export async function resolveConvexDeployment(secret, deployment = "prod") {
+    const parsed = CONVEX_SECRET_SCHEMA.parse(secret);
+    if ("deployKey" in parsed) {
+        if (deployment !== "prod") {
+            throw new Error("A deployment-key account is already bound to one deployment; omit the deployment option.");
+        }
+        return {
+            deploymentUrl: parsed.deploymentUrl,
+            reference: "connected",
+            token: parsed.deployKey,
+        };
+    }
+    const response = await fetch(`https://api.convex.dev/v1/projects/${encodeURIComponent(parsed.projectId)}/deployment?${new URLSearchParams(deployment === "prod"
+        ? { defaultProd: "true" }
+        : deployment === "dev"
+            ? { defaultDev: "true" }
+            : { reference: deployment }).toString()}`, { headers: { Authorization: `Bearer ${parsed.accessToken}` } });
+    if (!response.ok) {
+        throw new Error(`Convex could not resolve deployment ${deployment} (${response.status}).`);
+    }
+    const resolved = CONVEX_DEPLOYMENT_SCHEMA.parse(await response.json());
+    return {
+        deploymentUrl: resolved.deploymentUrl,
+        reference: resolved.reference,
+        token: parsed.accessToken,
+    };
+}
+/**
+ * Creates a small authenticated client for named Convex functions.
+ *
+ * @param secret - Persisted Convex account secret.
+ * @param deployment - Default alias or explicit deployment reference.
+ */
+export async function getConvexClient(secret, deployment = "prod") {
+    const resolved = await resolveConvexDeployment(secret, deployment);
+    return {
+        action: (functionName, arguments_) => requestConvexFunction("action", resolved, functionName, arguments_),
+        mutation: (functionName, arguments_) => requestConvexFunction("mutation", resolved, functionName, arguments_),
+        query: (functionName, arguments_) => requestConvexFunction("query", resolved, functionName, arguments_),
+    };
+}
+/**
+ * Runs a named Convex function through the authenticated deployment client.
+ *
+ * @param kind - Convex function kind.
+ * @param secret - Persisted Convex account secret.
+ * @param input - Function path, arguments, and deployment selection.
+ * @param input.arguments - Convex arguments keyed by parameter name.
+ * @param input.deployment - Default alias or explicit deployment reference.
+ * @param input.functionName - Exported Convex function path.
+ */
+export async function runConvexFunction(kind, secret, input) {
+    return await requestConvexFunction(kind, await resolveConvexDeployment(secret, input.deployment), input.functionName, input.arguments);
+}
+/**
+ * Returns the deployment API token stored by either connection method.
+ *
+ * @param secret - Persisted Convex account secret.
+ */
+export function getConvexDeploymentToken(secret) {
+    const parsed = CONVEX_SECRET_SCHEMA.parse(secret);
+    return "deployKey" in parsed ? parsed.deployKey : parsed.accessToken;
+}
+/**
+ * Decodes Convex's tagged JSON representation into a native Convex value.
+ *
+ * @param value - Tagged JSON returned by a Convex HTTP API.
+ */
+export function decodeConvexValue(value) {
+    return CONVEX_VALUE_SCHEMA.parse(jsonToConvex(value));
+}
+/**
+ * Encodes a native Convex value into Convex's tagged JSON representation.
+ *
+ * @param value - Native Convex value to encode.
+ */
+export function encodeConvexValue(value) {
+    return convexToJson(value);
+}
+/**
+ * Sends one authenticated Convex function request.
+ *
+ * @param kind - Convex function kind.
+ * @param deployment - Resolved URL and admin token.
+ * @param functionName - Exported function path.
+ * @param arguments_ - Convex arguments keyed by parameter name.
+ */
+async function requestConvexFunction(kind, deployment, functionName, arguments_ = {}) {
+    const response = await fetch(new URL(`/api/${kind}`, deployment.deploymentUrl), {
+        body: JSON.stringify({
+            args: [convexToJson(arguments_)],
+            format: "convex_encoded_json",
+            path: functionName,
+        }),
+        headers: {
+            Authorization: `Convex ${deployment.token}`,
+            "Content-Type": "application/json",
+        },
+        method: "POST",
+    });
+    if (!response.ok && response.status !== 560) {
+        const details = (await response.text()).trim();
+        throw new Error(`Convex function call failed (${response.status})${details ? `: ${details}` : "."}`);
+    }
+    const result = CONVEX_FUNCTION_RESPONSE_SCHEMA.parse(await response.json());
+    if (result.status === "error")
+        throw new Error(result.errorMessage);
+    return decodeConvexValue(result.value);
+}
+/**
+ * Checks a deployment-key connection and returns provider-owned identity.
+ *
+ * @param deploymentUrl - Connected Convex deployment URL.
+ * @param token - Convex deploy key.
+ */
+export async function getConvexDeploymentInfo(deploymentUrl, token) {
+    const response = await fetch(new URL("/api/v1/deployment_info", CONVEX_DEPLOYMENT_URL_SCHEMA.parse(deploymentUrl)), { headers: { Authorization: `Convex ${token}` } });
+    if (!response.ok) {
+        throw new Error(`Convex rejected the deployment key (${response.status}).`);
+    }
+    return CONVEX_DEPLOYMENT_INFO_SCHEMA.parse(await response.json());
+}
+/**
+ * Emits one authenticated semantic event from a Convex action.
+ *
+ * @param options - Endpoint, identity, payload, and signing secret.
+ */
+export async function emitConvexEvent(options) {
+    const timestamp = new Date().toISOString();
+    const body = JSON.stringify({
+        emittedAt: timestamp,
+        id: options.id,
+        name: options.name,
+        payload: encodeConvexValue(options.payload),
+    });
+    const response = await fetch(options.endpoint, {
+        body,
+        headers: {
+            "Content-Type": "application/json",
+            "x-automate-ax-event-id": options.id,
+            "x-automate-ax-signature": `sha256=${await signConvexEvent(options.signingSecret, timestamp, options.id, body)}`,
+            "x-automate-ax-timestamp": timestamp,
+        },
+        method: "POST",
+    });
+    if (!response.ok) {
+        throw new Error(`Automate.ax rejected the Convex event (${response.status}).`);
+    }
+}
+/**
+ * Computes the portable HMAC used by Convex semantic-event requests.
+ *
+ * @param secret - Shared webhook signing secret.
+ * @param timestamp - ISO timestamp included in the signature.
+ * @param eventId - Caller-assigned idempotency ID.
+ * @param body - Exact request body.
+ */
+export async function signConvexEvent(secret, timestamp, eventId, body) {
+    const encoder = new TextEncoder();
+    return Array.from(new Uint8Array(await crypto.subtle.sign("HMAC", await crypto.subtle.importKey("raw", encoder.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]), encoder.encode(`${timestamp}.${eventId}.${body}`))), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/convex/index.d.ts

@@ -0,0 +1,112 @@
+import * as z from "zod";
+export * from "./api.js";
+export * from "./schemas.js";
+export declare const CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA: z.ZodObject<{
+    component: z.ZodDefault<z.ZodString>;
+    deployment: z.ZodDefault<z.ZodString>;
+    table: z.ZodString;
+}, z.core.$strip>;
+export declare const CONVEX_EVENT_TRIGGER_CONFIG_SCHEMA: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export declare const convexTriggerContracts: {
+    readonly "convex.document.created": {
+        readonly configSchema: z.ZodObject<{
+            component: z.ZodDefault<z.ZodString>;
+            deployment: z.ZodDefault<z.ZodString>;
+            table: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            action: z.ZodEnum<{
+                deleted: "deleted";
+                created: "created";
+                updated: "updated";
+            }>;
+            component: z.ZodString;
+            document: z.ZodNullable<z.ZodObject<{
+                _creationTime: z.ZodOptional<z.ZodNumber>;
+                _id: z.ZodString;
+            }, z.core.$catchall<z.ZodOptional<z.ZodType<import("./schemas").ConvexValue, unknown, z.core.$ZodTypeInternals<import("./schemas").ConvexValue, unknown>>>>>>;
+            documentId: z.ZodString;
+            revision: z.ZodBigInt;
+            table: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly "convex.document.deleted": {
+        readonly configSchema: z.ZodObject<{
+            component: z.ZodDefault<z.ZodString>;
+            deployment: z.ZodDefault<z.ZodString>;
+            table: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            action: z.ZodEnum<{
+                deleted: "deleted";
+                created: "created";
+                updated: "updated";
+            }>;
+            component: z.ZodString;
+            document: z.ZodNullable<z.ZodObject<{
+                _creationTime: z.ZodOptional<z.ZodNumber>;
+                _id: z.ZodString;
+            }, z.core.$catchall<z.ZodOptional<z.ZodType<import("./schemas").ConvexValue, unknown, z.core.$ZodTypeInternals<import("./schemas").ConvexValue, unknown>>>>>>;
+            documentId: z.ZodString;
+            revision: z.ZodBigInt;
+            table: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly "convex.document.event": {
+        readonly configSchema: z.ZodObject<{
+            component: z.ZodDefault<z.ZodString>;
+            deployment: z.ZodDefault<z.ZodString>;
+            table: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            action: z.ZodEnum<{
+                deleted: "deleted";
+                created: "created";
+                updated: "updated";
+            }>;
+            component: z.ZodString;
+            document: z.ZodNullable<z.ZodObject<{
+                _creationTime: z.ZodOptional<z.ZodNumber>;
+                _id: z.ZodString;
+            }, z.core.$catchall<z.ZodOptional<z.ZodType<import("./schemas").ConvexValue, unknown, z.core.$ZodTypeInternals<import("./schemas").ConvexValue, unknown>>>>>>;
+            documentId: z.ZodString;
+            revision: z.ZodBigInt;
+            table: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly "convex.document.updated": {
+        readonly configSchema: z.ZodObject<{
+            component: z.ZodDefault<z.ZodString>;
+            deployment: z.ZodDefault<z.ZodString>;
+            table: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            action: z.ZodEnum<{
+                deleted: "deleted";
+                created: "created";
+                updated: "updated";
+            }>;
+            component: z.ZodString;
+            document: z.ZodNullable<z.ZodObject<{
+                _creationTime: z.ZodOptional<z.ZodNumber>;
+                _id: z.ZodString;
+            }, z.core.$catchall<z.ZodOptional<z.ZodType<import("./schemas").ConvexValue, unknown, z.core.$ZodTypeInternals<import("./schemas").ConvexValue, unknown>>>>>>;
+            documentId: z.ZodString;
+            revision: z.ZodBigInt;
+            table: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly "convex.event.received": {
+        readonly configSchema: z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            id: z.ZodString;
+            emittedAt: z.ZodISODateTime;
+            name: z.ZodString;
+            payload: z.ZodType<import("./schemas").ConvexValue, unknown, z.core.$ZodTypeInternals<import("./schemas").ConvexValue, unknown>>;
+        }, z.core.$strip>;
+    };
+};

package/dist/convex/index.js

@@ -0,0 +1,34 @@
+import * as z from "zod";
+import { CONVEX_DOCUMENT_EVENT_SCHEMA, CONVEX_SEMANTIC_EVENT_SCHEMA, } from "./schemas.js";
+export * from "./api.js";
+export * from "./schemas.js";
+export const CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA = z.object({
+    component: z.string().default(""),
+    deployment: z.string().default("prod"),
+    table: z.string().min(1),
+});
+export const CONVEX_EVENT_TRIGGER_CONFIG_SCHEMA = z.object({
+    name: z.string().min(1),
+});
+export const convexTriggerContracts = {
+    "convex.document.created": {
+        configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+        eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+    },
+    "convex.document.deleted": {
+        configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+        eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+    },
+    "convex.document.event": {
+        configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+        eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+    },
+    "convex.document.updated": {
+        configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+        eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+    },
+    "convex.event.received": {
+        configSchema: CONVEX_EVENT_TRIGGER_CONFIG_SCHEMA,
+        eventSchema: CONVEX_SEMANTIC_EVENT_SCHEMA,
+    },
+};

package/dist/convex/schemas.d.ts

@@ -0,0 +1,37 @@
+import * as z from "zod";
+/** Recursive schema for values accepted and returned by Convex functions. */
+export declare const CONVEX_VALUE_SCHEMA: z.ZodType<ConvexValue>;
+export type ConvexValue = null | boolean | number | bigint | string | ArrayBuffer | ConvexValue[] | {
+    [key: string]: ConvexValue | undefined;
+};
+export declare const CONVEX_DOCUMENT_SCHEMA: z.ZodObject<{
+    _creationTime: z.ZodOptional<z.ZodNumber>;
+    _id: z.ZodString;
+}, z.core.$catchall<z.ZodOptional<z.ZodType<ConvexValue, unknown, z.core.$ZodTypeInternals<ConvexValue, unknown>>>>>;
+export declare const CONVEX_DOCUMENT_EVENT_TYPES: readonly ["convex.document.event", "convex.document.created", "convex.document.updated", "convex.document.deleted"];
+export declare const CONVEX_DOCUMENT_ACTION_SCHEMA: z.ZodEnum<{
+    deleted: "deleted";
+    created: "created";
+    updated: "updated";
+}>;
+export declare const CONVEX_DOCUMENT_EVENT_SCHEMA: z.ZodObject<{
+    action: z.ZodEnum<{
+        deleted: "deleted";
+        created: "created";
+        updated: "updated";
+    }>;
+    component: z.ZodString;
+    document: z.ZodNullable<z.ZodObject<{
+        _creationTime: z.ZodOptional<z.ZodNumber>;
+        _id: z.ZodString;
+    }, z.core.$catchall<z.ZodOptional<z.ZodType<ConvexValue, unknown, z.core.$ZodTypeInternals<ConvexValue, unknown>>>>>>;
+    documentId: z.ZodString;
+    revision: z.ZodBigInt;
+    table: z.ZodString;
+}, z.core.$strip>;
+export declare const CONVEX_SEMANTIC_EVENT_SCHEMA: z.ZodObject<{
+    id: z.ZodString;
+    emittedAt: z.ZodISODateTime;
+    name: z.ZodString;
+    payload: z.ZodType<ConvexValue, unknown, z.core.$ZodTypeInternals<ConvexValue, unknown>>;
+}, z.core.$strip>;

package/dist/convex/schemas.js

@@ -0,0 +1,53 @@
+import * as z from "zod";
+/** Recursive schema for values accepted and returned by Convex functions. */
+export const CONVEX_VALUE_SCHEMA = z.lazy(() => z.union([
+    z.null(),
+    z.boolean(),
+    z.number(),
+    z.bigint(),
+    z.string(),
+    z.instanceof(ArrayBuffer),
+    z.array(CONVEX_VALUE_SCHEMA),
+    z.record(z.string(), CONVEX_VALUE_SCHEMA.optional()),
+]));
+export const CONVEX_DOCUMENT_SCHEMA = z
+    .object({
+    _creationTime: z.number().optional(),
+    _id: z.string(),
+})
+    .catchall(CONVEX_VALUE_SCHEMA.optional());
+export const CONVEX_DOCUMENT_EVENT_TYPES = [
+    "convex.document.event",
+    "convex.document.created",
+    "convex.document.updated",
+    "convex.document.deleted",
+];
+export const CONVEX_DOCUMENT_ACTION_SCHEMA = z.enum([
+    "created",
+    "updated",
+    "deleted",
+]);
+export const CONVEX_DOCUMENT_EVENT_SCHEMA = z.object({
+    /** Kind of lifecycle change observed for this document. */
+    action: CONVEX_DOCUMENT_ACTION_SCHEMA,
+    /** Convex component path, or an empty string for the root component. */
+    component: z.string(),
+    /** Current document, or `null` after deletion. */
+    document: CONVEX_DOCUMENT_SCHEMA.nullable(),
+    /** Stable Convex document ID. */
+    documentId: z.string(),
+    /** Monotonic Convex revision timestamp for this change. */
+    revision: z.bigint(),
+    /** Convex table containing the document. */
+    table: z.string(),
+});
+export const CONVEX_SEMANTIC_EVENT_SCHEMA = z.object({
+    /** Caller-assigned idempotency ID. */
+    id: z.string(),
+    /** ISO timestamp supplied by the emitting Convex action. */
+    emittedAt: z.iso.datetime({ offset: true }),
+    /** Application-defined semantic event name. */
+    name: z.string(),
+    /** Application-defined event payload. */
+    payload: CONVEX_VALUE_SCHEMA,
+});

package/dist/linear/schemas.d.ts

@@ -1704,10 +1704,7 @@ export declare const LINEAR_PROVIDER_PROJECT_SCHEMA: z.ZodObject<{
     name: z.ZodString;
     color: z.ZodString;
     completedAt: z.ZodNullable<z.ZodUnion<readonly [z.ZodDate, z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>]>>;
-    priority: z.ZodNumber;
     description: z.ZodString;
-    content: z.ZodNullable<z.ZodString>;
-    startDate: z.ZodNullable<z.ZodISODate>;
     url: z.ZodString;
     status: z.ZodObject<{
         color: z.ZodString;
@@ -1716,6 +1713,9 @@ export declare const LINEAR_PROVIDER_PROJECT_SCHEMA: z.ZodObject<{
         name: z.ZodString;
         type: z.ZodString;
     }, z.core.$strip>;
+    priority: z.ZodNumber;
+    content: z.ZodNullable<z.ZodString>;
+    startDate: z.ZodNullable<z.ZodISODate>;
     creator: z.ZodNullable<z.ZodObject<{
         active: z.ZodBoolean;
         avatarUrl: z.ZodNullable<z.ZodString>;
@@ -1807,10 +1807,10 @@ export declare const LINEAR_PROVIDER_ISSUE_SCHEMA: z.ZodObject<{
         title: z.ZodString;
         url: z.ZodString;
     }, z.core.$strip>>;
-    priority: z.ZodNumber;
+    title: z.ZodString;
     description: z.ZodNullable<z.ZodString>;
     url: z.ZodString;
-    title: z.ZodString;
+    priority: z.ZodNumber;
     creator: z.ZodNullable<z.ZodObject<{
         active: z.ZodBoolean;
         avatarUrl: z.ZodNullable<z.ZodString>;

package/dist/outlook/schemas.d.ts

@@ -491,8 +491,8 @@ export declare const OUTLOOK_ATTACHMENT_SCHEMA: z.ZodObject<{
     type: z.ZodEnum<{
         unknown: "unknown";
         file: "file";
-        item: "item";
         reference: "reference";
+        item: "item";
     }>;
 }, z.core.$strip>;
 export declare const GRAPH_ATTACHMENT_SCHEMA: z.ZodPipe<z.ZodObject<{
@@ -513,7 +513,7 @@ export declare const GRAPH_ATTACHMENT_SCHEMA: z.ZodPipe<z.ZodObject<{
     isInline: boolean;
     name: string;
     size: number;
-    type: "unknown" | "file" | "item" | "reference";
+    type: "unknown" | "file" | "reference" | "item";
     file?: File | undefined;
 }, {
     [x: string]: unknown;

package/dist/triggers.d.ts

@@ -1,6 +1,7 @@
 import type { airtableTriggerContracts } from "./airtable/index.js";
 import type { asanaTriggerContracts } from "./asana/index.js";
 import type { brevoTriggerContracts } from "./brevo/index.js";
+import type { convexTriggerContracts } from "./convex/index.js";
 import type { githubTriggerContracts } from "./github/index.js";
 import type { gmailTriggerContracts } from "./gmail/index.js";
 import type { googleCalendarTriggerContracts } from "./google-calendar/index.js";
@@ -15,7 +16,7 @@ import type { trelloTriggerContracts } from "./trello/index.js";
 import type { vercelTriggerContracts } from "./vercel/index.js";
 import type { whatsappTriggerContracts } from "./whatsapp/index.js";
 import type { z } from "zod";
-export type TriggerContractMap = typeof airtableTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof linearTriggerContracts & typeof outlookTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof whatsappTriggerContracts;
+export type TriggerContractMap = typeof airtableTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof convexTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof linearTriggerContracts & typeof outlookTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof whatsappTriggerContracts;
 export type IntegrationTriggerType = keyof TriggerContractMap;
 /** Canonical authoring configuration for one integration trigger type. */
 export type TriggerConfig<TType extends IntegrationTriggerType> = z.input<TriggerContractMap[TType]["configSchema"]> extends Record<string, never> ? object : z.input<TriggerContractMap[TType]["configSchema"]>;

package/dist/whatsapp/index.d.ts

@@ -324,6 +324,7 @@ export declare const whatsappTriggerContracts: {
                 type: z.ZodEnum<{
                     unknown: "unknown";
                     text: "text";
+                    document: "document";
                     system: "system";
                     location: "location";
                     image: "image";
@@ -332,7 +333,6 @@ export declare const whatsappTriggerContracts: {
                     audio: "audio";
                     button: "button";
                     contacts: "contacts";
-                    document: "document";
                     interactive: "interactive";
                     order: "order";
                     sticker: "sticker";
@@ -419,6 +419,7 @@ export declare const whatsappTriggerContracts: {
                 type: z.ZodEnum<{
                     unknown: "unknown";
                     text: "text";
+                    document: "document";
                     system: "system";
                     location: "location";
                     image: "image";
@@ -427,7 +428,6 @@ export declare const whatsappTriggerContracts: {
                     audio: "audio";
                     button: "button";
                     contacts: "contacts";
-                    document: "document";
                     interactive: "interactive";
                     order: "order";
                     sticker: "sticker";

package/dist/whatsapp/schemas.d.ts

@@ -90,6 +90,7 @@ export declare const WHATSAPP_WEBHOOK_SCHEMA: z.ZodObject<{
                     type: z.ZodEnum<{
                         unknown: "unknown";
                         text: "text";
+                        document: "document";
                         system: "system";
                         location: "location";
                         image: "image";
@@ -98,7 +99,6 @@ export declare const WHATSAPP_WEBHOOK_SCHEMA: z.ZodObject<{
                         audio: "audio";
                         button: "button";
                         contacts: "contacts";
-                        document: "document";
                         interactive: "interactive";
                         order: "order";
                         sticker: "sticker";
@@ -183,6 +183,7 @@ export declare const WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA: z.ZodObject<{
         type: z.ZodEnum<{
             unknown: "unknown";
             text: "text";
+            document: "document";
             system: "system";
             location: "location";
             image: "image";
@@ -191,7 +192,6 @@ export declare const WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA: z.ZodObject<{
             audio: "audio";
             button: "button";
             contacts: "contacts";
-            document: "document";
             interactive: "interactive";
             order: "order";
             sticker: "sticker";
@@ -278,6 +278,7 @@ export declare const WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA: z.ZodObject<{
         type: z.ZodEnum<{
             unknown: "unknown";
             text: "text";
+            document: "document";
             system: "system";
             location: "location";
             image: "image";
@@ -286,7 +287,6 @@ export declare const WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA: z.ZodObject<{
             audio: "audio";
             button: "button";
             contacts: "contacts";
-            document: "document";
             interactive: "interactive";
             order: "order";
             sticker: "sticker";
@@ -768,7 +768,7 @@ export declare function normalizeWhatsAppWebhook(input: unknown): {
         message: {
             id: string;
             timestamp: string;
-            type: "unknown" | "text" | "system" | "location" | "image" | "video" | "reaction" | "audio" | "button" | "contacts" | "document" | "interactive" | "order" | "sticker" | "unsupported";
+            type: "unknown" | "text" | "document" | "system" | "location" | "image" | "video" | "reaction" | "audio" | "button" | "contacts" | "interactive" | "order" | "sticker" | "unsupported";
             content?: z.core.util.JSONType | undefined;
             context?: {
                 messageId: string;
@@ -781,7 +781,7 @@ export declare function normalizeWhatsAppWebhook(input: unknown): {
             from: string;
             id: string;
             timestamp: string;
-            type: "unknown" | "text" | "system" | "location" | "image" | "video" | "reaction" | "audio" | "button" | "contacts" | "document" | "interactive" | "order" | "sticker" | "unsupported";
+            type: "unknown" | "text" | "document" | "system" | "location" | "image" | "video" | "reaction" | "audio" | "button" | "contacts" | "interactive" | "order" | "sticker" | "unsupported";
             audio?: {
                 id: string;
                 mime_type?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
       "./airtable": "./src/airtable/index.ts",
       "./asana": "./src/asana/index.ts",
       "./brevo": "./src/brevo/index.ts",
+      "./convex": "./src/convex/index.ts",
       "./gmail": "./src/gmail/index.ts",
       "./google-calendar": "./src/google-calendar/index.ts",
       "./google-forms": "./src/google-forms/index.ts",
@@ -42,13 +43,14 @@
     }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.82.0",
+    "@automate.ax/codec": "0.83.0",
     "@googleapis/calendar": "^15.0.0",
     "@googleapis/forms": "^6.0.1",
     "@googleapis/gmail": "^12.0.0",
     "@googleapis/meet": "^5.0.0",
     "@octokit/openapi-webhooks-types": "^12.1.0",
     "@octokit/rest": "^22.0.1",
+    "convex": "^1.45.0",
     "html-to-text": "^10.0.0",
     "nodemailer": "^9.0.3",
     "postal-mime": "^2.7.5",
@@ -56,7 +58,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@internal/config": "0.0.0",
+    "@internal/config": "0.1.0",
     "@types/bun": "latest",
     "@types/html-to-text": "^9.0.4",
     "@types/nodemailer": "^8.0.1",
@@ -101,6 +103,11 @@
       "types": "./dist/brevo/index.d.ts",
       "default": "./dist/brevo/index.js"
     },
+    "./convex": {
+      "bun": "./src/convex/index.ts",
+      "types": "./dist/convex/index.d.ts",
+      "default": "./dist/convex/index.js"
+    },
     "./gmail": {
       "bun": "./src/gmail/index.ts",
       "types": "./dist/gmail/index.d.ts",

package/src/convex/api.ts

@@ -0,0 +1,331 @@
+import { convexToJson, jsonToConvex } from "convex/values"
+import type { JSONValue } from "convex/values"
+import * as z from "zod"
+import { CONVEX_VALUE_SCHEMA, type ConvexValue } from "./schemas"
+
+const CONVEX_OAUTH_SECRET_SCHEMA = z.object({
+  accessToken: z.string(),
+  projectId: z.string(),
+})
+export const CONVEX_DEPLOYMENT_URL_SCHEMA = z.url().refine((value) => {
+  if (!URL.canParse(value)) return false
+  const url = new URL(value)
+  return (
+    url.protocol === "https:" &&
+    url.hostname.endsWith(".convex.cloud") &&
+    url.port === "" &&
+    url.username === "" &&
+    url.password === "" &&
+    url.pathname === "/" &&
+    url.search === "" &&
+    url.hash === ""
+  )
+}, "Enter a Convex Cloud deployment URL such as https://example.convex.cloud.")
+const CONVEX_DEPLOY_KEY_SECRET_SCHEMA = z.object({
+  deployKey: z.string(),
+  deploymentUrl: CONVEX_DEPLOYMENT_URL_SCHEMA,
+  webhookSecret: z.string(),
+})
+export const CONVEX_SECRET_SCHEMA = z.union([
+  CONVEX_OAUTH_SECRET_SCHEMA,
+  CONVEX_DEPLOY_KEY_SECRET_SCHEMA,
+])
+
+const CONVEX_DEPLOYMENT_SCHEMA = z.object({
+  deploymentUrl: CONVEX_DEPLOYMENT_URL_SCHEMA,
+  name: z.string(),
+  reference: z.string(),
+})
+const CONVEX_DEPLOYMENT_INFO_SCHEMA = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("cloud"),
+    projectId: z.string(),
+    projectName: z.string().nullable().optional(),
+    reference: z.string().nullable().optional(),
+  }),
+  z.object({ kind: z.literal("selfHosted") }),
+])
+const CONVEX_FUNCTION_RESPONSE_SCHEMA = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("success"), value: z.json() }),
+  z.object({ errorMessage: z.string(), status: z.literal("error") }),
+])
+
+export interface ConvexDeployment {
+  deploymentUrl: string
+  reference: string
+  token: string
+}
+
+/**
+ * Resolves the authenticated Convex deployment represented by an account.
+ *
+ * @param secret - Persisted Convex account secret.
+ * @param deployment - Default alias or explicit deployment reference.
+ */
+export async function resolveConvexDeployment(
+  secret: unknown,
+  deployment = "prod",
+): Promise<ConvexDeployment> {
+  const parsed = CONVEX_SECRET_SCHEMA.parse(secret)
+  if ("deployKey" in parsed) {
+    if (deployment !== "prod") {
+      throw new Error(
+        "A deployment-key account is already bound to one deployment; omit the deployment option.",
+      )
+    }
+    return {
+      deploymentUrl: parsed.deploymentUrl,
+      reference: "connected",
+      token: parsed.deployKey,
+    }
+  }
+
+  const response = await fetch(
+    `https://api.convex.dev/v1/projects/${encodeURIComponent(parsed.projectId)}/deployment?${new URLSearchParams(
+      deployment === "prod"
+        ? { defaultProd: "true" }
+        : deployment === "dev"
+          ? { defaultDev: "true" }
+          : { reference: deployment },
+    ).toString()}`,
+    { headers: { Authorization: `Bearer ${parsed.accessToken}` } },
+  )
+  if (!response.ok) {
+    throw new Error(
+      `Convex could not resolve deployment ${deployment} (${response.status}).`,
+    )
+  }
+  const resolved = CONVEX_DEPLOYMENT_SCHEMA.parse(await response.json())
+  return {
+    deploymentUrl: resolved.deploymentUrl,
+    reference: resolved.reference,
+    token: parsed.accessToken,
+  }
+}
+
+/**
+ * Creates a small authenticated client for named Convex functions.
+ *
+ * @param secret - Persisted Convex account secret.
+ * @param deployment - Default alias or explicit deployment reference.
+ */
+export async function getConvexClient(secret: unknown, deployment = "prod") {
+  const resolved = await resolveConvexDeployment(secret, deployment)
+  return {
+    action: (
+      functionName: string,
+      arguments_?: Record<string, ConvexValue | undefined>,
+    ) => requestConvexFunction("action", resolved, functionName, arguments_),
+    mutation: (
+      functionName: string,
+      arguments_?: Record<string, ConvexValue | undefined>,
+    ) => requestConvexFunction("mutation", resolved, functionName, arguments_),
+    query: (
+      functionName: string,
+      arguments_?: Record<string, ConvexValue | undefined>,
+    ) => requestConvexFunction("query", resolved, functionName, arguments_),
+  }
+}
+
+/**
+ * Runs a named Convex function through the authenticated deployment client.
+ *
+ * @param kind - Convex function kind.
+ * @param secret - Persisted Convex account secret.
+ * @param input - Function path, arguments, and deployment selection.
+ * @param input.arguments - Convex arguments keyed by parameter name.
+ * @param input.deployment - Default alias or explicit deployment reference.
+ * @param input.functionName - Exported Convex function path.
+ */
+export async function runConvexFunction(
+  kind: "action" | "mutation" | "query",
+  secret: unknown,
+  input: {
+    arguments?: Record<string, ConvexValue | undefined>
+    deployment?: string
+    functionName: string
+  },
+) {
+  return await requestConvexFunction(
+    kind,
+    await resolveConvexDeployment(secret, input.deployment),
+    input.functionName,
+    input.arguments,
+  )
+}
+
+/**
+ * Returns the deployment API token stored by either connection method.
+ *
+ * @param secret - Persisted Convex account secret.
+ */
+export function getConvexDeploymentToken(secret: unknown) {
+  const parsed = CONVEX_SECRET_SCHEMA.parse(secret)
+  return "deployKey" in parsed ? parsed.deployKey : parsed.accessToken
+}
+
+/**
+ * Decodes Convex's tagged JSON representation into a native Convex value.
+ *
+ * @param value - Tagged JSON returned by a Convex HTTP API.
+ */
+export function decodeConvexValue(value: JSONValue) {
+  return CONVEX_VALUE_SCHEMA.parse(jsonToConvex(value))
+}
+
+/**
+ * Encodes a native Convex value into Convex's tagged JSON representation.
+ *
+ * @param value - Native Convex value to encode.
+ */
+export function encodeConvexValue(value: ConvexValue) {
+  return convexToJson(value)
+}
+
+/**
+ * Sends one authenticated Convex function request.
+ *
+ * @param kind - Convex function kind.
+ * @param deployment - Resolved URL and admin token.
+ * @param functionName - Exported function path.
+ * @param arguments_ - Convex arguments keyed by parameter name.
+ */
+async function requestConvexFunction(
+  kind: "action" | "mutation" | "query",
+  deployment: ConvexDeployment,
+  functionName: string,
+  arguments_: Record<string, ConvexValue | undefined> = {},
+) {
+  const response = await fetch(
+    new URL(`/api/${kind}`, deployment.deploymentUrl),
+    {
+      body: JSON.stringify({
+        args: [convexToJson(arguments_)],
+        format: "convex_encoded_json",
+        path: functionName,
+      }),
+      headers: {
+        Authorization: `Convex ${deployment.token}`,
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    },
+  )
+  if (!response.ok && response.status !== 560) {
+    const details = (await response.text()).trim()
+    throw new Error(
+      `Convex function call failed (${response.status})${details ? `: ${details}` : "."}`,
+    )
+  }
+  const result = CONVEX_FUNCTION_RESPONSE_SCHEMA.parse(await response.json())
+  if (result.status === "error") throw new Error(result.errorMessage)
+  return decodeConvexValue(result.value)
+}
+
+/**
+ * Checks a deployment-key connection and returns provider-owned identity.
+ *
+ * @param deploymentUrl - Connected Convex deployment URL.
+ * @param token - Convex deploy key.
+ */
+export async function getConvexDeploymentInfo(
+  deploymentUrl: string,
+  token: string,
+) {
+  const response = await fetch(
+    new URL(
+      "/api/v1/deployment_info",
+      CONVEX_DEPLOYMENT_URL_SCHEMA.parse(deploymentUrl),
+    ),
+    { headers: { Authorization: `Convex ${token}` } },
+  )
+  if (!response.ok) {
+    throw new Error(`Convex rejected the deployment key (${response.status}).`)
+  }
+  return CONVEX_DEPLOYMENT_INFO_SCHEMA.parse(await response.json())
+}
+
+export interface EmitConvexEventOptions {
+  /** Public endpoint exposed by `onConvexEvent`. */
+  endpoint: string
+
+  /** Stable caller-assigned idempotency ID. */
+  id: string
+
+  /** Application-defined semantic event name. */
+  name: string
+
+  /** Convex-compatible payload delivered to the automation. */
+  payload: ConvexValue
+
+  /** Secret configured both on the account and in Convex. */
+  signingSecret: string
+}
+
+/**
+ * Emits one authenticated semantic event from a Convex action.
+ *
+ * @param options - Endpoint, identity, payload, and signing secret.
+ */
+export async function emitConvexEvent(options: EmitConvexEventOptions) {
+  const timestamp = new Date().toISOString()
+  const body = JSON.stringify({
+    emittedAt: timestamp,
+    id: options.id,
+    name: options.name,
+    payload: encodeConvexValue(options.payload),
+  })
+  const response = await fetch(options.endpoint, {
+    body,
+    headers: {
+      "Content-Type": "application/json",
+      "x-automate-ax-event-id": options.id,
+      "x-automate-ax-signature": `sha256=${await signConvexEvent(
+        options.signingSecret,
+        timestamp,
+        options.id,
+        body,
+      )}`,
+      "x-automate-ax-timestamp": timestamp,
+    },
+    method: "POST",
+  })
+  if (!response.ok) {
+    throw new Error(
+      `Automate.ax rejected the Convex event (${response.status}).`,
+    )
+  }
+}
+
+/**
+ * Computes the portable HMAC used by Convex semantic-event requests.
+ *
+ * @param secret - Shared webhook signing secret.
+ * @param timestamp - ISO timestamp included in the signature.
+ * @param eventId - Caller-assigned idempotency ID.
+ * @param body - Exact request body.
+ */
+export async function signConvexEvent(
+  secret: string,
+  timestamp: string,
+  eventId: string,
+  body: string,
+) {
+  const encoder = new TextEncoder()
+  return Array.from(
+    new Uint8Array(
+      await crypto.subtle.sign(
+        "HMAC",
+        await crypto.subtle.importKey(
+          "raw",
+          encoder.encode(secret),
+          { hash: "SHA-256", name: "HMAC" },
+          false,
+          ["sign"],
+        ),
+        encoder.encode(`${timestamp}.${eventId}.${body}`),
+      ),
+    ),
+    (byte) => byte.toString(16).padStart(2, "0"),
+  ).join("")
+}

package/src/convex/index.ts

@@ -0,0 +1,41 @@
+import * as z from "zod"
+import {
+  CONVEX_DOCUMENT_EVENT_SCHEMA,
+  CONVEX_SEMANTIC_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./api"
+export * from "./schemas"
+
+export const CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA = z.object({
+  component: z.string().default(""),
+  deployment: z.string().default("prod"),
+  table: z.string().min(1),
+})
+
+export const CONVEX_EVENT_TRIGGER_CONFIG_SCHEMA = z.object({
+  name: z.string().min(1),
+})
+
+export const convexTriggerContracts = {
+  "convex.document.created": {
+    configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+  },
+  "convex.document.deleted": {
+    configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+  },
+  "convex.document.event": {
+    configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+  },
+  "convex.document.updated": {
+    configSchema: CONVEX_DOCUMENT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: CONVEX_DOCUMENT_EVENT_SCHEMA,
+  },
+  "convex.event.received": {
+    configSchema: CONVEX_EVENT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: CONVEX_SEMANTIC_EVENT_SCHEMA,
+  },
+} as const

package/src/convex/schemas.ts

@@ -0,0 +1,79 @@
+import * as z from "zod"
+
+/** Recursive schema for values accepted and returned by Convex functions. */
+export const CONVEX_VALUE_SCHEMA: z.ZodType<ConvexValue> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.boolean(),
+    z.number(),
+    z.bigint(),
+    z.string(),
+    z.instanceof(ArrayBuffer),
+    z.array(CONVEX_VALUE_SCHEMA),
+    z.record(z.string(), CONVEX_VALUE_SCHEMA.optional()),
+  ]),
+)
+
+export type ConvexValue =
+  | null
+  | boolean
+  | number
+  | bigint
+  | string
+  | ArrayBuffer
+  | ConvexValue[]
+  | { [key: string]: ConvexValue | undefined }
+
+export const CONVEX_DOCUMENT_SCHEMA = z
+  .object({
+    _creationTime: z.number().optional(),
+    _id: z.string(),
+  })
+  .catchall(CONVEX_VALUE_SCHEMA.optional())
+
+export const CONVEX_DOCUMENT_EVENT_TYPES = [
+  "convex.document.event",
+  "convex.document.created",
+  "convex.document.updated",
+  "convex.document.deleted",
+] as const
+
+export const CONVEX_DOCUMENT_ACTION_SCHEMA = z.enum([
+  "created",
+  "updated",
+  "deleted",
+])
+
+export const CONVEX_DOCUMENT_EVENT_SCHEMA = z.object({
+  /** Kind of lifecycle change observed for this document. */
+  action: CONVEX_DOCUMENT_ACTION_SCHEMA,
+
+  /** Convex component path, or an empty string for the root component. */
+  component: z.string(),
+
+  /** Current document, or `null` after deletion. */
+  document: CONVEX_DOCUMENT_SCHEMA.nullable(),
+
+  /** Stable Convex document ID. */
+  documentId: z.string(),
+
+  /** Monotonic Convex revision timestamp for this change. */
+  revision: z.bigint(),
+
+  /** Convex table containing the document. */
+  table: z.string(),
+})
+
+export const CONVEX_SEMANTIC_EVENT_SCHEMA = z.object({
+  /** Caller-assigned idempotency ID. */
+  id: z.string(),
+
+  /** ISO timestamp supplied by the emitting Convex action. */
+  emittedAt: z.iso.datetime({ offset: true }),
+
+  /** Application-defined semantic event name. */
+  name: z.string(),
+
+  /** Application-defined event payload. */
+  payload: CONVEX_VALUE_SCHEMA,
+})

package/src/triggers.ts

@@ -1,6 +1,7 @@
 import type { airtableTriggerContracts } from "./airtable"
 import type { asanaTriggerContracts } from "./asana"
 import type { brevoTriggerContracts } from "./brevo"
+import type { convexTriggerContracts } from "./convex"
 import type { githubTriggerContracts } from "./github"
 import type { gmailTriggerContracts } from "./gmail"
 import type { googleCalendarTriggerContracts } from "./google-calendar"
@@ -19,6 +20,7 @@ import type { z } from "zod"
 export type TriggerContractMap = typeof airtableTriggerContracts &
   typeof asanaTriggerContracts &
   typeof brevoTriggerContracts &
+  typeof convexTriggerContracts &
   typeof githubTriggerContracts &
   typeof gmailTriggerContracts &
   typeof googleCalendarTriggerContracts &