@notionhq/workers 0.3.0 → 0.5.0

package/src/capabilities/workflow.ts

@@ -0,0 +1,119 @@
+import { ExecutionError } from "../error.js";
+import type {
+	WorkflowEventMap,
+	WorkflowTrigger,
+} from "../triggers.generated.js";
+import type { HandlerOptions } from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import { writeOutput } from "./output.js";
+
+export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
+
+export type WorkflowEventForTrigger<T extends WorkflowTrigger> =
+	WorkflowEventMap[T["type"]];
+
+export type WorkflowEventForTriggers<T extends readonly WorkflowTrigger[]> =
+	WorkflowEventForTrigger<T[number]>;
+
+/**
+ * Configuration for a workflow capability
+ */
+export type WorkflowConfiguration<
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+> = {
+	/**
+	 * A human-readable title for the workflow, shown in the UI when viewing workflows
+	 */
+	title: string;
+
+	/**
+	 * A human-readable description of what the workflow does, shown in the UI when viewing workflows
+	 */
+	description: string;
+
+	/**
+	 * An array of triggers that can invoke this workflow.
+	 *
+	 * Each trigger defines a specific event or condition that causes the workflow to run.
+	 */
+	triggers: TTriggers;
+
+	execute: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		context: CapabilityContext,
+	) => Promise<void> | void;
+};
+
+export type WorkflowCapability<
+	TTriggers extends readonly [
+		WorkflowTrigger,
+		...WorkflowTrigger[],
+	] = readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+> = {
+	_tag: "workflow";
+	key: string;
+	config: {
+		title: string;
+		description: string;
+		triggers: TTriggers;
+	};
+	handler: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		options?: HandlerOptions,
+	) => Promise<{ status: "success" } | undefined>;
+};
+
+/**
+ * Creates a workflow capability from configuration.
+ *
+ * @param key - The unique name for this capability.
+ * @param config - The workflow configuration.
+ * @returns The capability object.
+ */
+export function createWorkflowCapability<
+	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+>(
+	key: string,
+	config: WorkflowConfiguration<TTriggers>,
+): WorkflowCapability<TTriggers> {
+	return {
+		_tag: "workflow",
+		key,
+		config: {
+			title: config.title,
+			description: config.description,
+			triggers: config.triggers,
+		},
+		async handler(
+			event: WorkflowEventForTriggers<TTriggers>,
+			options?: HandlerOptions,
+		): Promise<{ status: "success" } | undefined> {
+			try {
+				const capabilityContext = createCapabilityContext("workflow");
+				await config.execute(event, capabilityContext);
+
+				if (options?.concreteOutput) {
+					return { status: "success" };
+				}
+
+				writeOutput({ _tag: "success", value: { status: "success" } });
+			} catch (err) {
+				const error = new ExecutionError(err);
+
+				if (!options?.concreteOutput) {
+					writeOutput({
+						_tag: "error",
+						error: {
+							name: error.name,
+							message: error.message,
+							trace: error.stack,
+						},
+					});
+				}
+
+				throw error;
+			}
+		},
+	};
+}

package/src/error.ts

@@ -11,6 +11,46 @@ export class ExecutionError extends Error {
 	}
 }
 
+/**
+ * Throw this error from your sync execute handler to signal that the
+ * external API returned a rate-limit response (e.g. HTTP 429).
+ *
+ * When the platform receives this error it applies exponential backoff
+ * instead of retrying immediately. If `retryAfter` is provided, the
+ * platform will wait at least that many seconds before the next attempt.
+ *
+ * @example
+ * ```ts
+ * worker.sync("issues", {
+ *   database: issuesDb,
+ *   execute: async (state, ctx) => {
+ *     const res = await fetch("https://api.example.com/issues");
+ *     if (res.status === 429) {
+ *       const retryAfter = Number(res.headers.get("Retry-After"));
+ *       throw new RateLimitError({
+ *         retryAfter: Number.isFinite(retryAfter) ? retryAfter : undefined,
+ *       });
+ *     }
+ *     // ...
+ *   },
+ * });
+ * ```
+ */
+export class RateLimitError extends ExecutionError {
+	/**
+	 * Optional number of seconds the external API asked us to wait
+	 * before retrying. The platform takes the max of this value and its
+	 * own exponential-backoff delay.
+	 */
+	readonly retryAfter: number | undefined;
+
+	constructor(options?: { retryAfter?: number }) {
+		super("Rate limited by external API");
+		this.name = "RateLimitError";
+		this.retryAfter = options?.retryAfter;
+	}
+}
+
 /**
  * Helper for exhaustive switch statements. TypeScript will error if a case is not handled.
  */

package/src/index.ts

@@ -1,4 +1,10 @@
-export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
+export {
+	emojiIcon,
+	imageCover,
+	imageIcon,
+	notionIcon,
+	place,
+} from "./builder.js";
 export type {
 	AiConnectorArchetype,
 	AiConnectorCapability,
@@ -37,18 +43,32 @@ export type {
 	SyncExecutionResult,
 	SyncMode,
 } from "./capabilities/sync.js";
-export type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
+export type {
+	ToolCapability,
+	ToolConfiguration,
+	ToolHints,
+} from "./capabilities/tool.js";
 export type {
 	WebhookCapability,
 	WebhookConfiguration,
 	WebhookEvent,
 } from "./capabilities/webhook.js";
 export { WebhookVerificationError } from "./capabilities/webhook.js";
+export type {
+	WorkflowCapability,
+	WorkflowConfiguration,
+	WorkflowEvent,
+	WorkflowEventForTrigger,
+	WorkflowEventForTriggers,
+} from "./capabilities/workflow.js";
+export { RateLimitError } from "./error.js";
 export type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
 export type { Infer, SchemaBuilder } from "./schema-builder.js";
 export { getSchema, j } from "./schema-builder.js";
 export type {
+	Cover,
 	Icon,
+	ImageCover,
 	ImageIcon,
 	NoticonColor,
 	NoticonName,

package/src/schema-builder.ts

@@ -94,6 +94,7 @@ function enumBuilder(
 	const type = typeof values[0] === "string" ? "string" : "number";
 	return makeBuilder({ type, enum: values } as AnyJSONSchema);
 }
+
 export { enumBuilder as enum };
 
 // ---- String format shorthands ----

package/src/triggers.generated.ts

@@ -0,0 +1,489 @@
+// Generated by scripts/generate-triggers.ts — do not edit by hand.
+// Regenerate with: npm run generate
+
+import type {
+	CalendarEventCanceledEvent,
+	CalendarEventCreatedEvent,
+	CalendarEventUpdatedEvent,
+	DiscordInteractionEvent,
+	GoogleDriveOauthFilesChangedEvent,
+	MailEmailReceivedEvent,
+	MailEmailSentEvent,
+	MailLabelAppliedEvent,
+	NotionAgentMentionedEvent,
+	NotionButtonPressedEvent,
+	NotionCommentAddedEvent,
+	NotionDatabaseAgentUpdatedEvent,
+	NotionMeetingNoteSummaryCompletedEvent,
+	NotionPageCreatedEvent,
+	NotionPageDeletedEvent,
+	NotionPageUpdatedEvent,
+	RecurrenceEvent,
+	SlackAppMentionEvent,
+	SlackMessageEvent,
+	SlackReactionAddedEvent,
+	WebhookEvent,
+} from "./triggers.js";
+
+export type {
+	Actor,
+	ActorLike,
+	CalendarEventCanceledEvent,
+	CalendarEventCreatedEvent,
+	CalendarEventLike,
+	CalendarEventUpdatedEvent,
+	ChatMessageLike,
+	ChatThreadMessage,
+	DiscordChatThreadMessage,
+	DiscordInteractionEvent,
+	EmailMessageLike,
+	EmailThreadLike,
+	EmailTriggerMessage,
+	GoogleDriveOauthFilesChangedEvent,
+	LinkLike,
+	MailEmailReceivedEvent,
+	MailEmailSentEvent,
+	MailLabelAppliedEvent,
+	MessageLike,
+	NotionAgentMentionedEvent,
+	NotionButtonPressedEvent,
+	NotionCommentAddedEvent,
+	NotionDatabaseAgentUpdatedEvent,
+	NotionMeetingNoteSummaryCompletedEvent,
+	NotionPageCreatedEvent,
+	NotionPageDeletedEvent,
+	NotionPageEdit,
+	NotionPageUpdatedEvent,
+	RecurrenceEvent,
+	RecurrenceFrequency,
+	SlackAppMentionEvent,
+	SlackChatThreadMessage,
+	SlackMessageEvent,
+	SlackReactionAddedEvent,
+	ThreadLike,
+	ThreadMessage,
+	TimestampLike,
+	TriggerEvent,
+	TriggerEventBase,
+	TriggerEventMap,
+	TriggerType,
+	VendorActor,
+	VendorExtensions,
+	WebhookEvent,
+} from "./triggers.js";
+
+/** A message was posted in a subscribed Slack channel. */
+export type SlackMessageTrigger = {
+	type: "slack.message";
+};
+
+/** A reaction was added to a Slack message. */
+export type SlackReactionAddedTrigger = {
+	type: "slack.reaction.added";
+};
+
+/** The Notion app was mentioned in a Slack message. */
+export type SlackAppMentionTrigger = {
+	type: "slack.app.mention";
+};
+
+/** A Discord interaction was received. */
+export type DiscordInteractionTrigger = {
+	type: "discord.interaction";
+};
+
+/** An email was received. */
+export type MailEmailReceivedTrigger = {
+	type: "mail.email.received";
+};
+
+/** An email was sent. */
+export type MailEmailSentTrigger = {
+	type: "mail.email.sent";
+};
+
+/** A label was applied to an email. */
+export type MailLabelAppliedTrigger = {
+	type: "mail.label.applied";
+};
+
+/** A calendar event was created. */
+export type CalendarEventCreatedTrigger = {
+	type: "calendar.event.created";
+};
+
+/** A calendar event was updated. */
+export type CalendarEventUpdatedTrigger = {
+	type: "calendar.event.updated";
+};
+
+/** A calendar event was canceled. */
+export type CalendarEventCanceledTrigger = {
+	type: "calendar.event.canceled";
+};
+
+/** A page has been added to a database. */
+export type NotionPageCreatedTrigger = {
+	type: "notion.page.created";
+};
+
+/** A page was updated. */
+export type NotionPageUpdatedTrigger = {
+	type: "notion.page.updated";
+};
+
+/** A page was deleted. */
+export type NotionPageDeletedTrigger = {
+	type: "notion.page.deleted";
+};
+
+/** A meeting note's AI summary finished generating. */
+export type NotionMeetingNoteSummaryCompletedTrigger = {
+	type: "notion.meetingNote.summary.completed";
+};
+
+/** A comment was added to a page discussion. */
+export type NotionCommentAddedTrigger = {
+	type: "notion.page.discussion.comment.added";
+};
+
+/** An agent was mentioned in page content or a person property. */
+export type NotionAgentMentionedTrigger = {
+	type: "notion.agent.mentioned";
+};
+
+/** A button block was pressed. */
+export type NotionButtonPressedTrigger = {
+	type: "notion.button.pressed";
+};
+
+/** A database agent's configuration was updated. */
+export type NotionDatabaseAgentUpdatedTrigger = {
+	type: "notion.database.agent.updated";
+};
+
+/** An incoming webhook request was received. */
+export type WebhookTrigger = {
+	type: "webhooks.webhook";
+};
+
+/** Files changed in a watched Google Drive folder or drive. */
+export type GoogleDriveOauthFilesChangedTrigger = {
+	type: "googleDriveOauth.filesChanged";
+};
+
+/** A recurring schedule fired. */
+export type RecurrenceTrigger = {
+	type: "recurrence";
+};
+
+/** Creators for each event that can trigger a workflow. */
+export const triggers = {
+	/**
+	 * Declare that a workflow can run on `slack.message` events.
+	 *
+	 * A message was posted in a subscribed Slack channel.
+	 */
+	slackMessage(): SlackMessageTrigger {
+		return {
+			type: "slack.message",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `slack.reaction.added` events.
+	 *
+	 * A reaction was added to a Slack message.
+	 */
+	slackReactionAdded(): SlackReactionAddedTrigger {
+		return {
+			type: "slack.reaction.added",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `slack.app.mention` events.
+	 *
+	 * The Notion app was mentioned in a Slack message.
+	 */
+	slackAppMention(): SlackAppMentionTrigger {
+		return {
+			type: "slack.app.mention",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `discord.interaction` events.
+	 *
+	 * A Discord interaction was received.
+	 */
+	discordInteraction(): DiscordInteractionTrigger {
+		return {
+			type: "discord.interaction",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `mail.email.received` events.
+	 *
+	 * An email was received.
+	 */
+	mailEmailReceived(): MailEmailReceivedTrigger {
+		return {
+			type: "mail.email.received",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `mail.email.sent` events.
+	 *
+	 * An email was sent.
+	 */
+	mailEmailSent(): MailEmailSentTrigger {
+		return {
+			type: "mail.email.sent",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `mail.label.applied` events.
+	 *
+	 * A label was applied to an email.
+	 */
+	mailLabelApplied(): MailLabelAppliedTrigger {
+		return {
+			type: "mail.label.applied",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `calendar.event.created` events.
+	 *
+	 * A calendar event was created.
+	 */
+	calendarEventCreated(): CalendarEventCreatedTrigger {
+		return {
+			type: "calendar.event.created",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `calendar.event.updated` events.
+	 *
+	 * A calendar event was updated.
+	 */
+	calendarEventUpdated(): CalendarEventUpdatedTrigger {
+		return {
+			type: "calendar.event.updated",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `calendar.event.canceled` events.
+	 *
+	 * A calendar event was canceled.
+	 */
+	calendarEventCanceled(): CalendarEventCanceledTrigger {
+		return {
+			type: "calendar.event.canceled",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.created` events.
+	 *
+	 * A page has been added to a database.
+	 */
+	notionPageCreated(): NotionPageCreatedTrigger {
+		return {
+			type: "notion.page.created",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.updated` events.
+	 *
+	 * A page was updated.
+	 */
+	notionPageUpdated(): NotionPageUpdatedTrigger {
+		return {
+			type: "notion.page.updated",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.deleted` events.
+	 *
+	 * A page was deleted.
+	 */
+	notionPageDeleted(): NotionPageDeletedTrigger {
+		return {
+			type: "notion.page.deleted",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.meetingNote.summary.completed` events.
+	 *
+	 * A meeting note's AI summary finished generating.
+	 */
+	notionMeetingNoteSummaryCompleted(): NotionMeetingNoteSummaryCompletedTrigger {
+		return {
+			type: "notion.meetingNote.summary.completed",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.discussion.comment.added` events.
+	 *
+	 * A comment was added to a page discussion.
+	 */
+	notionCommentAdded(): NotionCommentAddedTrigger {
+		return {
+			type: "notion.page.discussion.comment.added",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.agent.mentioned` events.
+	 *
+	 * An agent was mentioned in page content or a person property.
+	 */
+	notionAgentMentioned(): NotionAgentMentionedTrigger {
+		return {
+			type: "notion.agent.mentioned",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.button.pressed` events.
+	 *
+	 * A button block was pressed.
+	 */
+	notionButtonPressed(): NotionButtonPressedTrigger {
+		return {
+			type: "notion.button.pressed",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.database.agent.updated` events.
+	 *
+	 * A database agent's configuration was updated.
+	 */
+	notionDatabaseAgentUpdated(): NotionDatabaseAgentUpdatedTrigger {
+		return {
+			type: "notion.database.agent.updated",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `webhooks.webhook` events.
+	 *
+	 * An incoming webhook request was received.
+	 */
+	webhook(): WebhookTrigger {
+		return {
+			type: "webhooks.webhook",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `googleDriveOauth.filesChanged` events.
+	 *
+	 * Files changed in a watched Google Drive folder or drive.
+	 */
+	googleDriveOauthFilesChanged(): GoogleDriveOauthFilesChangedTrigger {
+		return {
+			type: "googleDriveOauth.filesChanged",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `recurrence` events.
+	 *
+	 * A recurring schedule fired.
+	 */
+	recurrence(): RecurrenceTrigger {
+		return {
+			type: "recurrence",
+		};
+	},
+} as const;
+
+/** Event that can trigger a workflow. */
+export type WorkflowTrigger =
+	| SlackMessageTrigger
+	| SlackReactionAddedTrigger
+	| SlackAppMentionTrigger
+	| DiscordInteractionTrigger
+	| MailEmailReceivedTrigger
+	| MailEmailSentTrigger
+	| MailLabelAppliedTrigger
+	| CalendarEventCreatedTrigger
+	| CalendarEventUpdatedTrigger
+	| CalendarEventCanceledTrigger
+	| NotionPageCreatedTrigger
+	| NotionPageUpdatedTrigger
+	| NotionPageDeletedTrigger
+	| NotionMeetingNoteSummaryCompletedTrigger
+	| NotionCommentAddedTrigger
+	| NotionAgentMentionedTrigger
+	| NotionButtonPressedTrigger
+	| NotionDatabaseAgentUpdatedTrigger
+	| WebhookTrigger
+	| GoogleDriveOauthFilesChangedTrigger
+	| RecurrenceTrigger;
+
+/** All workflow trigger type strings. */
+export const WORKFLOW_TRIGGER_TYPES = [
+	"slack.message",
+	"slack.reaction.added",
+	"slack.app.mention",
+	"discord.interaction",
+	"mail.email.received",
+	"mail.email.sent",
+	"mail.label.applied",
+	"calendar.event.created",
+	"calendar.event.updated",
+	"calendar.event.canceled",
+	"notion.page.created",
+	"notion.page.updated",
+	"notion.page.deleted",
+	"notion.meetingNote.summary.completed",
+	"notion.page.discussion.comment.added",
+	"notion.agent.mentioned",
+	"notion.button.pressed",
+	"notion.database.agent.updated",
+	"webhooks.webhook",
+	"googleDriveOauth.filesChanged",
+	"recurrence",
+] as const;
+
+/** A workflow trigger type string. */
+export type WorkflowTriggerType = (typeof WORKFLOW_TRIGGER_TYPES)[number];
+
+/** Maps each supported workflow trigger to the event its handler receives. */
+export type WorkflowEventMap = {
+	"slack.message": SlackMessageEvent;
+	"slack.reaction.added": SlackReactionAddedEvent;
+	"slack.app.mention": SlackAppMentionEvent;
+	"discord.interaction": DiscordInteractionEvent;
+	"mail.email.received": MailEmailReceivedEvent;
+	"mail.email.sent": MailEmailSentEvent;
+	"mail.label.applied": MailLabelAppliedEvent;
+	"calendar.event.created": CalendarEventCreatedEvent;
+	"calendar.event.updated": CalendarEventUpdatedEvent;
+	"calendar.event.canceled": CalendarEventCanceledEvent;
+	"notion.page.created": NotionPageCreatedEvent;
+	"notion.page.updated": NotionPageUpdatedEvent;
+	"notion.page.deleted": NotionPageDeletedEvent;
+	"notion.meetingNote.summary.completed": NotionMeetingNoteSummaryCompletedEvent;
+	"notion.page.discussion.comment.added": NotionCommentAddedEvent;
+	"notion.agent.mentioned": NotionAgentMentionedEvent;
+	"notion.button.pressed": NotionButtonPressedEvent;
+	"notion.database.agent.updated": NotionDatabaseAgentUpdatedEvent;
+	"webhooks.webhook": WebhookEvent;
+	"googleDriveOauth.filesChanged": GoogleDriveOauthFilesChangedEvent;
+	recurrence: RecurrenceEvent;
+};