@notionhq/workers 0.3.0 → 0.5.0

package/src/triggers.ts

@@ -0,0 +1,504 @@
+/**
+ * Agent Trigger Types — Public API
+ *
+ * Shared type definitions for agent triggers between @notionhq/workers and the Notion repository.
+ * This file MUST be kept identical in both repositories.
+ *
+ * Conventions:
+ *   - Protocols define the standard fields every consumer can rely on.
+ *   - Vendor-specific fields use `x-<vendor>-` prefix (e.g., "x-slack-threadId").
+ *   - Only public URLs — no internal URIs.
+ *   - No `data` sub-object — vendor fields live at the top level with `x-<vendor>-`.
+ *   - Types only — no runtime values.
+ *   - All fields are required. Nullable fields use `T | null` (no `?:`) so they
+ *     map directly to required + nullable in JSON Schema for LLM structured output.
+ *   - Conversions must always provide explicit values (use `null` when absent).
+ */
+
+// ============================================================
+// Vendor extension pattern
+// ============================================================
+
+/** Allows arbitrary vendor-specific fields prefixed with `x-<vendor>-`. */
+export type VendorExtensions = {
+	[key: `x-${string}`]: unknown
+}
+
+// ============================================================
+// Protocols (composable capabilities)
+// ============================================================
+
+/** Has a human-readable message / summary. */
+export type MessageLike = {
+	message: string
+}
+
+/** Has an actor who performed the action. */
+export type ActorLike = {
+	actor: Actor | null
+}
+
+/** Has a navigable URL. */
+export type LinkLike = {
+	url: string | null
+}
+
+/** Has a timestamp. */
+export type TimestampLike = {
+	/** ISO 8601 */
+	timestamp: string | null
+}
+
+/** Has a conversation thread. */
+export type ThreadLike<M = ThreadMessage> = {
+	thread: Array<M>
+	/** Whether this event is a follow-up in a previously subscribed thread. */
+	isFollowUpMessage: boolean | null
+}
+
+/**
+ * A chat message. Any chat platform (Slack, Discord, MS Teams, etc.) implements this.
+ * Composes MessageLike, ActorLike, LinkLike, TimestampLike.
+ */
+export type ChatMessageLike = MessageLike &
+	ActorLike &
+	LinkLike &
+	TimestampLike & {
+		id: string
+		channelId: string
+		channelName: string | null
+	}
+
+/** An email message. Any mail provider (Gmail, Outlook, etc.) implements this. */
+export type EmailMessageLike = MessageLike &
+	LinkLike &
+	TimestampLike & {
+		id: string
+		subject: string
+		from: string
+		fromName: string | null
+		to: Array<string>
+		cc: Array<string> | null
+		bcc: Array<string> | null
+		/** Plain-text or HTML body content. */
+		body: string
+		isRead: boolean | null
+		hasAttachments: boolean | null
+		labels: Array<string> | null
+	}
+
+/** An email thread. Any mail provider implements this. */
+export type EmailThreadLike = {
+	id: string
+	subject: string
+	participants: Array<string>
+	messageCount: number
+	/** ISO 8601 */
+	lastMessageAt: string
+	hasUnread: boolean
+}
+
+/** A calendar event. Any calendar provider (Google, Outlook, iCal, etc.) implements this. */
+export type CalendarEventLike = LinkLike &
+	TimestampLike & {
+		eventId: string
+		summary: string
+		description: string | null
+		location: string | null
+		/** ISO 8601 */
+		startTime: string
+		/** ISO 8601 */
+		endTime: string | null
+		isAllDay: boolean | null
+		isRecurring: boolean | null
+		attendees: Array<Actor> | null
+		calendarId: string
+		accountId: string
+	}
+
+// ============================================================
+// Core types
+// ============================================================
+
+/**
+ * An actor who performed an action.
+ *
+ * `id` / `displayName` / `email` are the Notion-resolved identity.
+ * `vendorActor` carries the identity in the originating system.
+ */
+export type Actor = {
+	/** Notion user ID (when resolved). */
+	id: string | null
+	displayName: string | null
+	email: string | null
+	/** The actor's identity in the vendor system. */
+	vendorActor: VendorActor | null
+}
+
+/** Vendor-specific actor identity. */
+export type VendorActor = {
+	/** Vendor name: "slack", "gmail", "discord", "notion", etc. */
+	vendor: string
+	/** Vendor-specific ID. */
+	id: string
+	displayName: string | null
+	/** Handle / username (e.g., Slack @handle). */
+	handle: string | null
+	/** "user", "bot", or a vendor-specific string. */
+	type: "user" | "bot" | string | null
+	/** URL to the actor's profile in the vendor system. */
+	url: string | null
+}
+
+// ============================================================
+// Thread message
+// ============================================================
+
+/**
+ * A single message inside a thread.
+ * Implements MessageLike, ActorLike, LinkLike, TimestampLike.
+ * Vendor-specific fields use `x-<vendor>-` prefix.
+ */
+export type ThreadMessage = MessageLike &
+	ActorLike &
+	LinkLike &
+	TimestampLike &
+	VendorExtensions & {
+		id: string
+	}
+
+/** A chat thread message. Extends ChatMessageLike with VendorExtensions. */
+export type ChatThreadMessage = ChatMessageLike & VendorExtensions
+
+/** An email message in a trigger. Extends EmailMessageLike with VendorExtensions. */
+export type EmailTriggerMessage = EmailMessageLike & VendorExtensions
+
+// ============================================================
+// Trigger event base
+// ============================================================
+
+/**
+ * Every trigger event has at least these fields.
+ * `message` is a human-readable summary of what happened.
+ */
+export type TriggerEventBase = MessageLike &
+	ActorLike &
+	VendorExtensions & {
+		type: string
+		vendor: string
+	}
+
+/**
+ * Base shape for chat trigger events (Slack, Discord, MS Teams, etc.).
+ * Parameterized on the message type so each platform can narrow
+ * `triggerMessage` and `thread` to its vendor-specific message shape.
+ */
+type ChatEventBase<M extends ChatThreadMessage = ChatThreadMessage> =
+	TriggerEventBase &
+		LinkLike &
+		TimestampLike &
+		ThreadLike<M> & {
+			/** The message that fired the trigger. */
+			triggerMessage: M
+			channelId: string
+			channelName: string | null
+			threadId: string | null
+		}
+
+// ============================================================
+// Slack
+// ============================================================
+
+export type SlackChatThreadMessage = ChatThreadMessage & {
+	"x-slack-fileUrls": Array<string> | null
+	/** URLs extracted from the message text. */
+	"x-slack-urls": Array<string> | null
+}
+
+export type SlackMessageEvent = ChatEventBase<SlackChatThreadMessage> & {
+	type: "slack.message"
+	vendor: "slack"
+}
+
+export type SlackReactionAddedEvent = ChatEventBase<SlackChatThreadMessage> & {
+	type: "slack.reaction.added"
+	vendor: "slack"
+	/** The emoji name (without colons), e.g. "thumbsup". */
+	"x-slack-reaction": string | null
+}
+
+export type SlackAppMentionEvent = ChatEventBase<SlackChatThreadMessage> & {
+	type: "slack.app.mention"
+	vendor: "slack"
+}
+
+// ============================================================
+// Mail
+// ============================================================
+
+/** Base shape for all mail trigger events. */
+type MailEventBase = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		vendor: "notionmail" | "gmail" | string
+		/** The triggering email. */
+		email: EmailTriggerMessage
+		/** The email thread this message belongs to. */
+		emailThread: EmailThreadLike
+		/** The email address of the mailbox owner. */
+		userEmail: string
+	}
+
+export type MailEmailReceivedEvent = MailEventBase & {
+	type: "mail.email.received"
+}
+
+export type MailEmailSentEvent = MailEventBase & {
+	type: "mail.email.sent"
+}
+
+export type MailLabelAppliedEvent = MailEventBase & {
+	type: "mail.label.applied"
+	/** The label that was applied. */
+	appliedLabel: string
+}
+
+// ============================================================
+// Calendar
+// ============================================================
+
+/** Base shape for all calendar trigger events. */
+type CalendarEventBase = TriggerEventBase &
+	CalendarEventLike & {
+		vendor: "notion-calendar" | "google" | string
+	}
+
+export type CalendarEventCreatedEvent = CalendarEventBase & {
+	type: "calendar.event.created"
+}
+
+export type CalendarEventUpdatedEvent = CalendarEventBase & {
+	type: "calendar.event.updated"
+	/** Which fields changed. */
+	updatedFields: Array<string> | null
+}
+
+export type CalendarEventCanceledEvent = CalendarEventBase & {
+	type: "calendar.event.canceled"
+}
+
+// ============================================================
+// Discord
+// ============================================================
+
+export type DiscordChatThreadMessage = ChatThreadMessage & {
+	"x-discord-guildId": string | null
+}
+
+export type DiscordInteractionEvent =
+	ChatEventBase<DiscordChatThreadMessage> & {
+		type: "discord.interaction"
+		vendor: "discord"
+		"x-discord-guildId": string | null
+	}
+
+// ============================================================
+// Notion — Page / Database triggers
+// ============================================================
+
+/** A property edit with before/after snapshots. */
+export type NotionPageEdit = {
+	before: Record<string, unknown> | null
+	after: Record<string, unknown> | null
+	afterContent: string | null
+	contentChanged: boolean | null
+	timestamp: number
+	editedBy: Actor | null
+}
+
+export type NotionPageCreatedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.created"
+		vendor: "notion"
+		/** Page properties as key-value pairs. */
+		page: Record<string, unknown>
+		/** Rendered markdown content of the page. */
+		content: string
+		edits: Array<NotionPageEdit> | null
+	}
+
+export type NotionPageUpdatedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.updated"
+		vendor: "notion"
+		/** Chronological array of edits (accumulated during debounce). */
+		edits: Array<NotionPageEdit>
+	}
+
+export type NotionPageDeletedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.deleted"
+		vendor: "notion"
+		page: Record<string, unknown>
+		content: string
+	}
+
+export type NotionMeetingNoteSummaryCompletedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.meetingNote.summary.completed"
+		vendor: "notion"
+		page: Record<string, unknown>
+		content: string
+		meetingNoteBlockId: string
+	}
+
+// ============================================================
+// Notion — Discussion / Comment triggers
+// ============================================================
+
+export type NotionCommentAddedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.discussion.comment.added"
+		vendor: "notion"
+		/** The full discussion context. */
+		discussion: {
+			id: string
+			pageId: string
+			resolved: boolean
+			context: "inline" | "block" | "page" | "databaseProperty" | null
+			parentBlockId: string | null
+			propertyId: string | null
+			propertyName: string | null
+		}
+		/** The new comment. */
+		comment: {
+			id: string
+			text: string
+			url: string
+			timestamp: string
+			actor: Actor | null
+		}
+	}
+
+// ============================================================
+// Notion — Agent / Button triggers
+// ============================================================
+
+export type NotionAgentMentionedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.agent.mentioned"
+		vendor: "notion"
+		page: Record<string, unknown>
+		content: string
+		mentionLocation: "page_content" | "person_property"
+		mentionBlockContent: string | null
+		propertyId: string | null
+		propertyName: string | null
+	}
+
+export type NotionButtonPressedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.button.pressed"
+		vendor: "notion"
+		blockUrl: string
+	}
+
+export type NotionDatabaseAgentUpdatedEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "notion.database.agent.updated"
+		vendor: "notion"
+		agentId: string
+		runtimeInstructions: string
+		shouldRunOverDatabase: boolean
+		viewId: string | null
+	}
+
+export type WebhookEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "webhooks.webhook"
+		vendor: "webhooks"
+		triggerId: string
+		verificationSchema: string
+		eventType: string | null
+		deliveryId: string | null
+		payload: unknown
+	}
+
+// ============================================================
+// Google Drive OAuth — File changed (polling) trigger
+// ============================================================
+
+export type GoogleDriveOauthFilesChangedEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "googleDriveOauth.filesChanged"
+		vendor: "google-drive"
+		/** The page token from before this poll. */
+		changeToken: string
+		/** The page token after this poll. */
+		newChangeToken: string
+		/** Number of changes detected. */
+		changeCount: number
+		/** The folder or drive being watched. */
+		scope:
+			| { type: "folder"; folderId: string }
+			| { type: "drive"; driveId: string }
+		/** Upper time bound for this poll window (ISO 8601). */
+		lastEventTimestamp: string
+	}
+
+// ============================================================
+// Recurrence (scheduled) trigger
+// ============================================================
+
+export type RecurrenceFrequency = "hour" | "day" | "week" | "month" | "year"
+
+export type RecurrenceEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "recurrence"
+		vendor: "notion"
+		frequency: RecurrenceFrequency
+		interval: number
+		timezone: string
+	}
+
+// ============================================================
+// Derived union types
+// ============================================================
+
+/** Map from trigger type string to its event shape. Single source of truth. */
+export type TriggerEventMap = {
+	"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
+}
+
+/** All trigger type strings. Derived from TriggerEventMap. */
+export type TriggerType = keyof TriggerEventMap
+
+/** Discriminated union of all trigger events. Derived from TriggerEventMap. */
+export type TriggerEvent = TriggerEventMap[TriggerType]

package/src/types.ts

@@ -182,6 +182,26 @@ export interface ImageIcon {
  */
 export type Icon = EmojiIcon | NoticonIcon | ImageIcon;
 
+/**
+ * Cover image for a Notion page.
+ */
+export interface ImageCover {
+	type: "image";
+	/**
+	 * The URL of the image (must be a valid http/https URL)
+	 */
+	url: string;
+	/**
+	 * Vertical image position, from 0 (top) to 1 (bottom).
+	 */
+	position?: number;
+}
+
+/**
+ * All possible cover types
+ */
+export type Cover = ImageCover;
+
 /**
  * Person reference - represents a user in a people property
  */

package/src/worker.ts

@@ -31,24 +31,33 @@ import {
 	createWebhookCapability,
 	WebhookVerificationError,
 } from "./capabilities/webhook.js";
+import type {
+	WorkflowCapability,
+	WorkflowConfiguration,
+	WorkflowEvent,
+} from "./capabilities/workflow.js";
+import { createWorkflowCapability } from "./capabilities/workflow.js";
 import type { PacerDeclaration } from "./pacer_internal.js";
 import { pacerWait } from "./pacer_internal.js";
 import type { Schema } from "./schema.js";
+import type { WorkflowTrigger } from "./triggers.generated.js";
 import type { HandlerOptions, JSONValue } from "./types.js";
 
 // Re-export types for convenience
 export type {
+	AiConnectorConfiguration,
 	AutomationConfiguration,
 	AutomationEvent,
-	AiConnectorConfiguration,
 	CapabilityContext,
-	OAuthConfiguration,
 	NotionManagedOAuthConfiguration,
-	UserManagedOAuthConfiguration,
+	OAuthConfiguration,
 	SyncConfiguration,
 	ToolConfiguration,
+	UserManagedOAuthConfiguration,
 	WebhookConfiguration,
 	WebhookEvent,
+	WorkflowConfiguration,
+	WorkflowEvent,
 };
 export { WebhookVerificationError };
 
@@ -62,6 +71,49 @@ type Capability =
 	// biome-ignore lint/suspicious/noExplicitAny: tool capabilities are generic over arbitrary input/output payloads.
 	| ToolCapability<any, any>
 	| AutomationCapability
+	| WorkflowCapability
+	| OAuthCapability
+	| WebhookCapability;
+
+export type CapabilityType = Capability["_tag"];
+
+// ============================================================================
+// Internal capability storage
+// ============================================================================
+//
+// Registration methods return capabilities whose handler parameters are
+// narrowed to the inputs they declared (e.g. a workflow handler only
+// accepts events for its declared triggers). Handlers are contravariant in
+// those parameters, so the narrowed capabilities are not assignable to the
+// all-inputs members of `Capability`. Rather than cast them, the internal
+// store is honest about this type erasure: stored handlers take `never`,
+// recording that the store cannot prove what each handler accepts. `run()`
+// is the single place that re-asserts the platform's contract that the
+// incoming context matches the capability's declared input.
+
+/** A tool capability as stored: its input/output types are erased. */
+type StoredToolCapability = Omit<
+	Extract<Capability, { _tag: "tool" }>,
+	"handler"
+> & {
+	handler: (input: never, options?: HandlerOptions) => Promise<unknown>;
+};
+
+/** A workflow capability as stored: its event type is erased. */
+type StoredWorkflowCapability = Omit<WorkflowCapability, "handler"> & {
+	handler: (
+		event: never,
+		options?: HandlerOptions,
+	) => Promise<{ status: "success" } | undefined>;
+};
+
+/** How `Worker` stores registered capabilities internally. */
+type StoredCapability =
+	| SyncCapability
+	| AiConnectorCapability
+	| StoredToolCapability
+	| AutomationCapability
+	| StoredWorkflowCapability
 	| OAuthCapability
 	| WebhookCapability;
 
@@ -196,7 +248,7 @@ const SDK_VERSION = (() => {
 // ============================================================================
 
 export class Worker {
-	#capabilities: Map<string, Capability> = new Map();
+	#capabilities: Map<string, StoredCapability> = new Map();
 	#databases: Map<string, RegisteredDatabase> = new Map();
 	#pacers: Map<string, PacerDeclaration> = new Map();
 
@@ -407,8 +459,7 @@ export class Worker {
 	): ToolCapability<I, O> {
 		this.#validateUniqueKey(key);
 		const capability = createToolCapability(key, config);
-		// biome-ignore lint/suspicious/noExplicitAny: any is used to allow any input and output types
-		this.#capabilities.set(key, capability as ToolCapability<any, any>);
+		this.#capabilities.set(key, capability);
 		return capability;
 	}
 
@@ -454,6 +505,45 @@ export class Worker {
 		return capability;
 	}
 
+	/**
+	 * Register a workflow capability.
+	 *
+	 * Example:
+	 *
+	 * ```ts
+	 * import { Worker } from "@notionhq/workers";
+	 * import { triggers } from "@notionhq/workers/triggers";
+	 *
+	 * const worker = new Worker();
+	 * export default worker;
+	 *
+	 * worker.workflow("sendWelcomeEmail", {
+	 *   title: "Send Welcome Email",
+	 *   description: "Sends a welcome email when a new user is added",
+	 *   triggers: [triggers.notionPageCreated()],
+	 *   execute: async (event) => {
+	 *     console.log(event.page);
+	 *     console.log(event.content);
+	 *   },
+	 * })
+	 * ```
+	 *
+	 * @param key - The unique key for this capability.
+	 * @param config - The workflow configuration.
+	 * @returns The capability object.
+	 */
+	workflow<
+		const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+	>(
+		key: string,
+		config: WorkflowConfiguration<TTriggers>,
+	): WorkflowCapability<TTriggers> {
+		this.#validateUniqueKey(key);
+		const capability = createWorkflowCapability(key, config);
+		this.#capabilities.set(key, capability);
+		return capability;
+	}
+
 	/**
 	 * Register a webhook capability.
 	 *
@@ -586,8 +676,11 @@ export class Worker {
 			throw new Error(`Capability "${key}" cannot be executed`);
 		}
 
-		// biome-ignore lint/suspicious/noExplicitAny: context is unknown, passed by external non-typed code.
-		return capability.handler(context as any, options);
+		// The store erases handler parameter types to `never` (see
+		// `StoredCapability`); the platform guarantees the context passed by
+		// external code matches the capability's declared input, so re-assert
+		// that contract here.
+		return capability.handler(context as never, options);
 	}
 
 	#validateUniqueKey(key: string): void {